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

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

Jonathan Corbet <corbet@lwn.net> writes:

> Donald Hunter <donald.hunter@gmail.com> writes:
>
>> Run make in list of subdirs to build generated sources and migrate
>> userspace-api/media to use this instead of being a special case.
>>
>> Signed-off-by: Donald Hunter <donald.hunter@gmail.com>
>
> This could really use a bit more information on exactly what you're
> doing and why you want to do it.

What would you like me to add? Something like:

"... in preparation for running a generator script to produce .csv data
used by bpf documentation"

> 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.