On Fri, Sep 30, 2022 at 2:58 AM Donald Hunter <donald.hunter@xxxxxxxxx> wrote: > > Donald Hunter <donald.hunter@xxxxxxxxx> writes: > > > Jonathan Corbet <corbet@xxxxxxx> writes: > > > >> Beyond that, I would *really* like to see more use of Sphinx extensions > >> for this kind of special-case build rather than hacking in more > >> special-purpose scripts. Is there a reason why it couldn't be done that > >> way? > > > > I looked at writing the BPF program types as a Sphinx extension but > > found that approach problematic for the following reasons: > > > > - This needs to run both in the kernel tree and the libbpf Github > > project. The tree layouts are different so the relative paths to > > source files are different. I don't see an elegant way to handle this > > inline in a .rst file. This can easily be handled in Makefiles > > that are specific to each project. > > > > - It makes use of csv-table which does all the heavy lifting to produce > > the desired output. > > > > - I have zero experience of extending Sphinx. > > > > I thought about submitting this directly to the libbpf Github project > > and then just linking from the kernel docs to the page about program > > types in the libbpf project docs. But I think it is preferable to master > > the gen-bpf-progtypes.sh script in the kernel tree where it can be > > maintained in the same repo as the libbpf.c source file it parses. > > Given the pushback on Makefile changes and the need for this patch to be > compatible with both the kernel tree and the libbpf repo, can I suggest > a pragmatic way forward. > > I suggest that I drop the gen-bpf-progtypes.sh script and Makefile It's way too easy to forget to update this table when adding new program type support in libbpf. So if possible I think script is the way to go. Jonathan, given the script is really minimal and allows to keep documentation in sync with libbpf source code, do you have a strong objection? Writing a custom plugin seems like a too high bar for something pretty straightforward like this? Also, should this be routed through your tree or you'd like us to take it through bpf-next tree? Donald, if Jonathan is feeling really strongly, then I guess manually generated table is ok approach as well, but let's hear from Jonathan first. Also cc Grant about logistics of kernel vs libbpf docs. > changes from the patchset and just submit static documentation contents > for the table of BPF program types. This would avoid any downstream > breakage when syncing from the kernel tree to the libbpf github > repo. The table of BPF program types can be maintained manually which > should not be a burden going forward. Another benefit would be that the > resulting documentation can be curated more easily than if it were > auto-generated.
