Skip to contentSkip to conversation

Convert test catalog (docparse) from asciidoc to readthedocs.io (sphinx)

RFC Petr Vorel 2 participants 3 messages Dec 27, 2024 – Dec 30, 2024

lore
Share & tools
lore

Petr Vorel

author
#0 lore raw

Hi

I suggest to convert test catalog ("docparse") generated by docparse/testinfo.pl and asciidoc/asciidoctor to sphinx generator (readthedocs.io). asciidoc/asciidoctor was a good choice at the time, but now it looks to me better to use sphinx for everything.

I volunteer to do the work, but I would like to have a general agreement before I do it.

Pros:

* We already have attempt to show tested syscalls [1]. Printing test catalog would have more info.
* No need to install dependencies.
* Automatic. If we add also doc for stable releases, it would replace the need to install dependencies and upload file to LTP release on GitHub [2]. Then only link to page to test coverage on linux-test-project.readthedocs.io of particular release (or link to whole doc on particular release) would be added in release mail announcement (or we might keep adding generated pdf/epub/zipped html also to LTP releases [2]).
* Unified look and feel.

Work needed:

* Convert docparse/testinfo.pl to doc/conf.py, obviously change from asciidoc to spinx.
* Adding stable releases (not sure if it can be created automatically for all tags).
* Adding offline formats [3] so that users can download the docs (that would be useful anyway).

Kind regards,
Petr

[1] https://linux-test-project.readthedocs.io/en/latest/users/stats.html
[2] https://github.com/linux-test-project/ltp/releases
[3] https://docs.readthedocs.io/en/stable/downloadable-documentation.html

Signature · 1 line
Mailing list info: https://lists.linux.it/listinfo/ltp
author
#1 lore raw
Quoted 10 lines

Hi

I suggest to convert test catalog ("docparse") generated by docparse/testinfo.pl and asciidoc/asciidoctor to sphinx generator (readthedocs.io). asciidoc/asciidoctor was a good choice at the time, but now it looks to me better to use sphinx for everything.

I volunteer to do the work, but I would like to have a general agreement before I do it.

Quoted 6 lines

Pros:

* We already have attempt to show tested syscalls [1]. Printing test catalog would have more info.
* No need to install dependencies.
* Automatic. If we add also doc for stable releases, it would replace the need

NOTE: stable release doc was already active. One can switch via floating box on bottom right.

Kind regards,
Petr

Quoted 22 lines

to install dependencies and upload file to LTP release on GitHub [2]. Then only link to page to test coverage on linux-test-project.readthedocs.io of particular release (or link to whole doc on particular release) would be added in release mail announcement (or we might keep adding generated pdf/epub/zipped html also to LTP releases [2]).
* Unified look and feel.

Work needed:

* Convert docparse/testinfo.pl to doc/conf.py, obviously change from asciidoc to spinx.
* Adding stable releases (not sure if it can be created automatically for all tags).
* Adding offline formats [3] so that users can download the docs (that would be useful anyway).

Kind regards,
Petr

[1] https://linux-test-project.readthedocs.io/en/latest/users/stats.html
[2] https://github.com/linux-test-project/ltp/releases
[3] https://docs.readthedocs.io/en/stable/downloadable-documentation.html

Signature · 1 line
Mailing list info: https://lists.linux.it/listinfo/ltp
#2 lore raw
In reply to Petr Vorel
Quoted 8 lines · Petr Vorel

Hi

I suggest to convert test catalog ("docparse") generated by docparse/ testinfo.pl
and asciidoc/asciidoctor to sphinx generator (readthedocs.io). asciidoc/asciidoctor was a good choice at the time, but now it looks to me better to use sphinx for everything.

Agree.

Quoted 4 lines

I volunteer to do the work, but I would like to have a general agreement before
I do it.

Thanks, the Linux Kernel has shifted from AsciiDoc to reStructuredText as part of its Documentation overhaul. So It is reasonable for LTP to do this as well.

Quoted 40 lines

Pros:

* We already have attempt to show tested syscalls [1]. Printing test catalog would
have more info.
* No need to install dependencies.
* Automatic. If we add also doc for stable releases, it would replace the need
to install dependencies and upload file to LTP release on GitHub [2]. Then only
link to page to test coverage on linux-test-project.readthedocs.io of particular
release (or link to whole doc on particular release) would be added in release
mail announcement (or we might keep adding generated pdf/epub/zipped html also
to LTP releases [2]).
* Unified look and feel.

Work needed:

* Convert docparse/testinfo.pl to doc/conf.py, obviously change from asciidoc
to spinx.
* Adding stable releases (not sure if it can be created automatically for all
tags).
* Adding offline formats [3] so that users can download the docs (that would be
useful anyway).

Kind regards,
Petr

[1] https://linux-test-project.readthedocs.io/en/latest/users/stats.html
[2] https://github.com/linux-test-project/ltp/releases
[3] https://docs.readthedocs.io/en/stable/downloadable-documentation.html

Signature · 5 lines
Regards,
Li Wang

-- 
Mailing list info: https://lists.linux.it/listinfo/ltp