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

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

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

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

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

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

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

> 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

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

Kind regards,
Petr

> 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

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

Re: [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

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