[LTP] [Open discussion] docparse handling

[LTP] [Open discussion] docparse handling

[Andrea Cervesato via ltp]

Hi all,

we just added a test catalog in the LTP documentation [1], but most of 
the tests are still using asciidoc as the main tests' description 
syntax. Obviously, we need to switch to RST [2] syntax, that is now used 
in the whole LTP documentation along with sphinx [3] support.

I would like to introduce a discussion on this topic, since I seen a few 
patches meant to adapt old tests' descriptions [4] into asciidoc and we 
don't really want to double our job. In particular:

- is [Description] tag still needed? Shall we use **Description** instead?
- shall we start to convert all tests' descriptions into asciidoc? If 
yes, how? Automatically or manually?

Best regards,
Andrea Cervesato

[1] 
https://linux-test-project.readthedocs.io/en/latest/users/test_catalog.html
[2] https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
[3] https://www.sphinx-doc.org/en/master/index.html
[4] 
https://patchwork.ozlabs.org/project/ltp/patch/20250210091044.359274-1-maxj.fnst@fujitsu.com/


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

Re: [LTP] [Open discussion] docparse handling

[pvorel]

On 2025-02-10 13:25, Andrea Cervesato via ltp wrote:
> Hi all,
> 
> we just added a test catalog in the LTP documentation [1], but most of
> the tests are still using asciidoc as the main tests' description
> syntax. Obviously, we need to switch to RST [2] syntax, that is now
> used in the whole LTP documentation along with sphinx [3] support.

Yes, we need to convert to RST (fix formatting and get rid of warnings 
and errors from sphinx).

> I would like to introduce a discussion on this topic, since I seen a
> few patches meant to adapt old tests' descriptions [4] into asciidoc
> and we don't really want to double our job. In particular:
> 
> - is [Description] tag still needed? Shall we use **Description** 
> instead?

This would mean plain bold. The original motivation was that this should 
be a header (not plain bold) and we did not want to embed the header 
level in source code (Cyril, please, correct me if I'm wrong). E.g. this 
is not related to RST, it's a special LTP formatting.

Although title is more suitable than bold, I'm ok with have the others 
(e.g. [Algorithm]) formatted as bold. But I really suggest to remove 
[Description] entirely [1] because IMHO it does not add any information 
value and therefore it just prolong the page.

Originally I noted the reason for removal that it's missing in some CVE 
tests (inconsistency).
Cyril proposed to fix this problem in the code [2], but I would really 
prefer to remove it.

Kind regards,
Petr

[1] https://lore.kernel.org/ltp/20250131115828.GB1116925@pevik/
[2] https://lore.kernel.org/ltp/Z5y03QTwjlgsuJ88@yuki.lan/

> - shall we start to convert all tests' descriptions into asciidoc? If
> yes, how? Automatically or manually?
> 
> Best regards,
> Andrea Cervesato
> 
> [1] 
> https://linux-test-project.readthedocs.io/en/latest/users/test_catalog.html
> [2] 
> https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
> [3] https://www.sphinx-doc.org/en/master/index.html
> [4] 
> https://patchwork.ozlabs.org/project/ltp/patch/20250210091044.359274-1-maxj.fnst@fujitsu.com/

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