[LTP] New LTP documentation!

[Andrea Cervesato]

Hi Petr,

On 3/18/24 18:01, Petr Vorel wrote:
> 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?
I don't think it's possible. One it's meant to be github pages while 
readthedocs is hosted somewhere else in https://readthedocs.org/
>> 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.
As far as I know, both github and gitlab support RST and the idea is to 
rewrite README as well, because it contains multiple errors and it will 
be replaced by index.rst
>> 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).
Yes, we will use Doxygen. It will come in a second phase, after 
refactoring the whole documentation into RST.
>
> 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

I also forgot to mention that Sphinx is highly customizable due to the 
python scripting, so we can generate static pages at build time, 
introducing (for example) versions release letters and many other things.

Best regards,
Andrea