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

[Grant Seltzer Richman <grantseltzer@gmail.com>]

On Thu, Apr 29, 2021 at 6:57 PM Jonathan Corbet <corbet@lwn.net> wrote:
>
> 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?

Hm, yes I do agree that it'd be nice to use existing tooling but I
just have a couple concerns for this but please point me in the right
direction because i'm sure i'm missing something. I was told to ask on
the linux-doc mailing list because you'd have valuable input anway.
This is based on reading
https://www.kernel.org/doc/html/v4.9/kernel-documentation.html#including-kernel-doc-comments

1. We'd want the ability to pull documentation from the code itself to
make it so documentation never falls out of date with code. Based on
the docs on kernel.org/doc it seems that we'd have to be explicit with
specifying which functions/types are included in an .rst file and
submit a patch to update the documentation everytime the libbpf api
changes. Perhaps if this isn't a thing already I can figure out how to
contribute it.

2. Would it be possible (or necessary) to separate libbpf
documentation from the kernel readthedocs page since libbpf isn't part
of the kernel?

Thanks so much,
Grant

> Thanks,
>
> jon