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

[Andrii Nakryiko <andrii.nakryiko@gmail.com>]

On Tue, Jun 1, 2021 at 11:58 AM Jonathan Corbet <corbet@lwn.net> wrote:
>
> grantseltzer <grantseltzer@gmail.com> writes:
>
> > This patch series 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.
> >
> > In this approach the generated API documentation is enabled by the kernels
> > existing kernel documentation system which uses sphinx. The resulting docs
> > would then be synced to kernel.org/doc
> >
> > You can test this by running `make htmldocs` and serving the html in
> > Documentation/output. Since libbpf does not yet have comments in kernel
> > doc format, see kernel.org/doc/html/latest/doc-guide/kernel-doc.html for
> > an example so you can test this.
> >
> > The advantage of this approach is to use the existing sphinx
> > infrastructure that the kernel has, and have libbpf docs in
> > the same place as everything else.
> >
> > The perhaps large disadvantage of this approach is that libbpf versions
> > independently from the kernel. If it's possible to version libbpf
> > separately without having duplicates that would be the ideal scenario.
>
> I'm happy to see things going this direction; it looks like a good start
> to me.
>
> Let me know if you'd like this to go through the docs tree, or feel free
> to add:
>
>   Acked-by: Jonathan Corbet <corbet@lwn.net>

Thanks, Jonathan! I prefer to take this through bpf-next, which will
make it easier to keep it in sync on Github (if we do that, of
course).

>
> if you want to route it via some other path.
>
> Thanks,
>
> jon