On Mon, May 10, 2021 at 7:59 AM Grant Seltzer Richman <grantseltzer@xxxxxxxxx> wrote: > > On Fri, Apr 30, 2021 at 1:31 PM Andrii Nakryiko > <andrii.nakryiko@xxxxxxxxx> wrote: > > > > On Fri, Apr 30, 2021 at 7:27 AM Grant Seltzer Richman > > <grantseltzer@xxxxxxxxx> wrote: > > > > > > On Fri, Apr 30, 2021 at 10:22 AM Jonathan Corbet <corbet@xxxxxxx> wrote: > > > > > > > > Grant Seltzer Richman <grantseltzer@xxxxxxxxx> 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. No worries. Thanks for the update! > > > > > > > > > > > > > > Thanks, > > > > > > > > jon
