[LTP] [RFC] Convert test catalog (docparse) from asciidoc to readthedocs.io (sphinx)

[Li Wang]

On Fri, Dec 27, 2024 at 3:39 PM Petr Vorel <pvorel@suse.cz> wrote:

> 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.


> 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.



>
> 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
>
>

-- 
Regards,
Li Wang