Re: [LTP] New LTP documentation!

[Petr Vorel <pvorel@suse.cz>]

Hi Andrea, all,

First, thank you for doing this POC.

> Hello everyone,

> as already mentioned in the monthly LTP meeting, Linux Test Project lacks of
> a nice and clean documentation that can be easily accessed by users,
> developers and maintainers.

This was from the start confusing for me, because we have docs in wiki and
metadata documentation. But the text below explains the main advantage :).

> The current LTP documentation is also not matching with our expectancy
> towards the entire project, which is has been heavily refactored and it has
> changed in the past years, providing a higher quality code and new testing
> features.

> For this reasons, we think it's time to move forward and to start working on
> documentation, helping people to use, to develop and to maintain LTP in an
> easier way, increasing quality of the overall project and to call more
> developers in the community.

> I started to work on documentation refactoring, re-organizing the overall
> structure. The first prototype can be found here:

> https://ltp-acerv.readthedocs.io/en/latest/index.html

+1, nice POC. I see from your github LTP fork it's generated via
.readthedocs.yml - +1 for docs sources staying in LTP main repository and
generated as a result of simple push.

I wonder what to make with our static page:

https://linux-test-project.github.io/

Could we somehow redirect it to our github URL or to docs on readthedocs.io?

> The idea is to move documents from the current asciidoc format to RST
> format, following the current kernel docs guide lines [1], and to move API
> headers descriptions from regular C comments to Doxygen format.

IMHO library docs generated with Doxygen is IMHO the main advantage.

> By using the powerful readthedocs service [2], it's possible to deploy a
> documentation website with one simple setup, using Sphinx [3] as the main
> documentation framework.

Maybe, we could later generate our metadata docs with Sphinx. To have single
source

Although markdown is supported elsewhere (if we one day want to migrate e.g. to
gitlab), using readthedocs.

> For now, website prototype is showing a couple of pages, but the overall
> structure is there and ready to be filled.

> The purpose of this email is to ask for feedback and ideas from the LTP
> community, so we can make documentation even better. Let me know what you
> think.

+1

I hope you plan to do the conversion and plan in the future to add Doxygen
generated docs (to actually add more content than what we have now with github
wiki).

Kind regards,
Petr

> Have a good day,
> Andrea Cervesato


> [1] https://docs.kernel.org/doc-guide/sphinx.html#writing-documentation
> [2] https://about.readthedocs.com/?ref=readthedocs.com
> [3] https://www.sphinx-doc.org/en/master

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