From: Grant Seltzer Richman <grantseltzer@gmail.com>
To: Andrii Nakryiko <andrii.nakryiko@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>,
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: Mon, 10 May 2021 10:58:52 -0400 [thread overview]
Message-ID: <CAO658oWPrEDBE8FUBuDUnrBVM91Mgu-svXfXgAXawAUp1MmWZA@mail.gmail.com> (raw)
In-Reply-To: <CAEf4BzZJUtPiGn+8mkzNd2k+-3EEE85_xezab3RYy9ZW4zqANQ@mail.gmail.com>
On Fri, Apr 30, 2021 at 1:31 PM Andrii Nakryiko
<andrii.nakryiko@gmail.com> wrote:
>
> On Fri, Apr 30, 2021 at 7:27 AM Grant Seltzer Richman
> <grantseltzer@gmail.com> wrote:
> >
> > On Fri, Apr 30, 2021 at 10:22 AM Jonathan Corbet <corbet@lwn.net> wrote:
> > >
> > > Grant Seltzer Richman <grantseltzer@gmail.com> writes:
> > >
> > > > 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.
> > >
> > > No, you can tell it to pull out docs for all of the functions in a given
> > > file. You only need to name things if you want to narrow things down.
> >
> > Alright, I will figure out how to do this and adjust the patch
> > accordingly. My biggest overall goal is making it as easy as possible
> > to contribute documentation. I think even adding just one doc string
> > above an API function is a great opportunity for new contributors to
> > familiarize themselves with the mailing list/patch process.
> >
> > >
> > > > 2. Would it be possible (or necessary) to separate libbpf
> > > > documentation from the kernel readthedocs page since libbpf isn't part
> > > > of the kernel?
> > >
> > > It could certainly be built as a separate "book", as are many of the
> > > kernel books now. I could see it as something that gets pulled into the
> > > user-space API book, but there could also perhaps be an argument made
> > > for creating a new "libraries" book instead.
> >
> > Yea if I can figure this out for the libbpf API it'd be great to
> > replicate it for any API!
>
> It would be great if it was possible to have this libbpf
> auto-generated documentation as part of the kernel documentation, but
> also be able to generate and export it into our Github mirror to be
> pulled by readthedocs.io. If that can be done, it would be the best of
> both kernel and external worlds. We have a sync script that already
> auto-generates and checks in BPF helpers header, so we have a
> precedent of checking in auto-generated stuff into Github. So it's
> mostly about figuring out the mechanics of doc generation.
Agreed, the mirror will have to bring in the documentation
subdirectory as well so the output could be seperate.
Just want to update in this thread that i've been really preoccupied
with other obligations and will get back to this next week.
>
> >
> > >
> > > Thanks,
> > >
> > > jon
next prev parent reply other threads:[~2021-05-10 15:24 UTC|newest]
Thread overview: 24+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-04-29 5:47 [PATCH bpf-next 0/3] Autogenerating API documentation grantseltzer
2021-04-29 5:47 ` [PATCH bpf-next 1/3] bpf: Add sphinx documentation build files grantseltzer
2021-04-29 5:47 ` [PATCH bpf-next 2/3] bpf: Add doxygen configuration file grantseltzer
2021-04-29 5:47 ` [PATCH bpf-next 3/3] bpf: Add rst docs for libbpf grantseltzer
2021-04-29 22:57 ` [PATCH bpf-next 0/3] Autogenerating API documentation Jonathan Corbet
2021-04-30 14:04 ` Grant Seltzer Richman
2021-04-30 14:22 ` Jonathan Corbet
2021-04-30 14:27 ` Grant Seltzer Richman
2021-04-30 17:30 ` Andrii Nakryiko
2021-05-10 14:58 ` Grant Seltzer Richman [this message]
2021-05-10 17:48 ` Andrii Nakryiko
2021-05-26 3:22 ` Grant Seltzer Richman
2021-05-26 20:45 ` Andrii Nakryiko
2021-05-28 14:50 ` Grant Seltzer Richman
2021-06-01 19:01 ` Jonathan Corbet
2021-06-01 22:49 ` Grant Seltzer Richman
2021-06-01 23:19 ` Jonathan Corbet
2021-06-02 1:06 ` Grant Seltzer Richman
2021-06-04 21:18 ` Grant Seltzer Richman
2021-06-07 22:45 ` Andrii Nakryiko
2021-06-09 17:04 ` Grant Seltzer Richman
2021-06-10 17:14 ` Andrii Nakryiko
2021-06-11 20:00 ` Grant Seltzer Richman
2021-06-14 22:35 ` Andrii Nakryiko
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=CAO658oWPrEDBE8FUBuDUnrBVM91Mgu-svXfXgAXawAUp1MmWZA@mail.gmail.com \
--to=grantseltzer@gmail.com \
--cc=andrii.nakryiko@gmail.com \
--cc=andrii@kernel.org \
--cc=bpf@vger.kernel.org \
--cc=corbet@lwn.net \
--cc=daniel@iogearbox.net \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).