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

From: Grant Seltzer Richman <grantseltzer@gmail.com>
To: Jonathan Corbet <corbet@lwn.net>
Cc: Andrii Nakryiko <andrii.nakryiko@gmail.com>,
	Andrii Nakryiko <andrii@kernel.org>,
	Daniel Borkmann <daniel@iogearbox.net>, bpf <bpf@vger.kernel.org>
Subject: Re: [PATCH bpf-next 0/3] Autogenerating API documentation
Date: Fri, 4 Jun 2021 17:18:53 -0400	[thread overview]
Message-ID: <CAO658oXRN=JnP+e=qM2-uBu94BxoWCyHcScOgSwxpoHOw5ByLQ@mail.gmail.com> (raw)
In-Reply-To: <CAO658oWwqtZFnhVg3hC8dO=2obOKn5Mp2uqrOYa-3xsNwiRU8Q@mail.gmail.com>

On Tue, Jun 1, 2021 at 9:06 PM Grant Seltzer Richman
<grantseltzer@gmail.com> wrote:
>
> On Tue, Jun 1, 2021 at 7:19 PM Jonathan Corbet <corbet@lwn.net> wrote:
> >
> > Grant Seltzer Richman <grantseltzer@gmail.com> writes:
> >
> > > Andrii cuts releases of libbpf using the github mirror at
> > > github.com/libbpf/libbpf. There's more context in the README there,
> > > but most of the major distributions package libbpf from this mirror.
> > > Since developers that use libbpf in their applications include libbpf
> > > based on these github releases instead of versions of Linux (i.e. I
> > > use libbpf 0.4, not libbpf from linux 5.14), it's important to have
> > > the API documentation be labeled by the github release versions. Is
> > > there any mechanism in the kernel docs that would allow us to do that?
> > > Would it make more sense for the libbpf community to maintain their
> > > own documentation system/website for this purpose?
> >
> > It depends on how you want that labeling to look, I guess.  One simple
> > thing might be to put a DOC: block into the libbpf code that holds the
> > version number, then use a kernel-doc directive to pull it in in the
> > appropriate place.  Alternatives might include adding a bit of magic to
> > Documentation/conf.py to fetch a "#define VERSION# out of the source
> > somewhere and stash the information away.
>
> Gotcha, I will investigate these approaches. Thanks!

After investigating/attempting these approaches, my opinion is that it
would be better to have a separate libbpf documentation system (sphinx
configuration files). This way we can maintain separate versions of
the documentation for each release/version without having duplicate
pages, and without having to heavily change the kernel docs files to
fit libbpf specific needs.

If you check out libbpf.readthedocs.io you can see what that would
look like. I made a test release (v21.21.21) to show how easy this is.
That is being pulled from my PR at github.com/libbpf/libbpf/pull/260.

I'm fine with having this new sphinx configuration in the kernel tree,
I'm also fine with having it on the github mirror. Both make sense to
me. Either way the comment docs have to be submitted through the
mailing list.

One last idea I have is to have the non-api docs (for example, the
document describing naming convention in libbpf) in the kernel tree,
and sync it in the github mirror.

Please feel free to ask questions, I've been thinking a lot about
this! Once we decide on which way to go I can have this up and running
almost immediately.
> >
> > If you're wanting to replace the version code that appears at the top of
> > the left column in the HTML output, though, it's going to be a bit
> > harder.  I don't doubt we can do it, but it may require messing around
> > with template files and such.
> >
> > Thanks,
> >
> > jon