Re: [PATCH bpf-next 0/3] Autogenerating API documentation

[Jonathan Corbet <corbet@lwn.net>]

grantseltzer <grantseltzer@gmail.com> writes:

> This series of patches is meant to start the initiative to document libbpf.
> It includes .rst files which are text documentation describing building, 
> API naming convention, as well as an index to generated API documentation.

So I'm totally in favor of documenting libbpf...

> The generated API documentation is enabled by Doxygen, which actually 
> parses the code for documentation comment strings and generates XML.
> A tool called Sphinx then reads this XML with the help of the breathe
> plugin, as well as the above mentioned .rst files and generates beautiful
> HTML output.
>
> The goal of this is for readthedocs.io to be able to pick up that generated
> documentation which will be made possible with the help of readthedoc's 
> github integration and libbpf's official github mirror. Minor setup 
> is required in that mirror once this patch series is merged.

...but I do have to wonder why you are doing something outside of the
kernel's documentation system, which just happens to be based on a tool
called Sphinx.  It would be Really Nice to have this documentation part
of our doc tree; it would also be good to not bring in yet another tool
for building kernel docs.

Do you really need to do your own thing here?

Thanks,

jon