[LTP] [PATCH 00/10] New LTP documentation

[Andrea Cervesato]

Hi Petr!

On 3/21/24 09:25, Petr Vorel wrote:
> Hi Andrea,
>
>> The new LTP documentation is meant to use Sphinx as the main
>> documentation framework, with ReconStructedText as the main language.
>> All the conversion has been done step-by-step, each chapter at time,
>> updating english syntax and fixing typos. There are minor improvements,
>> but overall the structure is the same.
>> C / Networking / KVM API are not documented yet, because they will be
>> probably integrated in the LTP library. C API documentation is already
>> on going, but the others not.
>> For a demo, please take a look at:
>> https://ltp-acerv.readthedocs.io/en/latest/index.html
> Out of curiosity, we need to register LTP on readthedocs.io.
> Then we need GitHub Action hook (including some secret for auth) for publishing.
> Correct?
>
> https://docs.readthedocs.io/en/stable/guides/setup/git-repo-manual.html
readthedocs works with any kind of git server. The only thing we need, 
it's a .readthedocs.yaml file inside a specific branch (i.e. master).
So we need to create an account for the LTP team in readthedocs.com, 
then we provide the git repo to readthedocs and site will be published 
automatically.
ltp.readthedocs.io is available, so maybe we should create an account 
already.
>
> I guess you now deploy to your fork manually, otherwise you would add GitHub
> Action config in the patchset.
It's automatic done by readthedocs and we don't need Github actions.
>
> Also, what I like (for the future) offline formats (PDF, ePub, HTML) are
> supported:
>
> https://docs.readthedocs.io/en/stable/downloadable-documentation.html
Sure we can try to generate it and see what happens. I never tried to do 
it in sphinx.
>
> Also, I would prefer when this merged it would actually replace the old github
> docs (otherwise we maintainers endup maintaining both - getting fixes for both).
> E.g. in the final version first deleting the old docs + github update hook.
Sure, so let's finish the basics. I'm waiting for Cyril LTP library 
documentation, since I don't have all the expertise which are requested. 
The idea is that we will get rid of the current C-Test-API.asciidoc file 
and we will only use documented headers.
Then we can proceed for sure.
>
> Kind regards,
> Petr

We also have networking/KVM/shell API documentation that should be 
placed inside the headers. It would be nice to have a help on that.

Regards,
Andrea