Re: [PATCH bpf-next v4 1/2] Add subdir support to Documentation makefile

[Donald Hunter <donald.hunter@gmail.com>]

Donald Hunter <donald.hunter@gmail.com> writes:

> Jonathan Corbet <corbet@lwn.net> 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
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.