On Wed, 20 Jul 2022 at 10:50, Alejandro Colomar <alx.manpages@xxxxxxxxx> wrote:
>
> Hi Rumen,
>
> On 7/19/22 19:21, Rumen Telbizov wrote:
> > Hi Alejandro,
> >
> > Thanks for following up on this.
> > Quentin will send you the script these days for you to rerun.
> > However, I'm wondering if there's a way to run it automatically when a change is
> > detected or otherwise without needing manual intervention? This way
> > the published
> > page will not get out of date. I am not sure what that mechanism might be but
> > just a thought.
>
> I'm not sure an automated mechanism would be easy to set up.
> But, I'm planning to add a RELEASE file to the man-pages repo with
> instructions to make a release. I can add there a step that reminds to
> refresh the bpf-helpers(7) manual page before every release.
Hi Alejandro, Rumen,
Thank you Rumen for raising this. Yes, the bpf-helpers(7) man page is
generated from a script: it's scripts/bpf_doc.py under the kernel
repository [0], which parses the UAPI header at
include/uapi/linux/bpf.h [1] to generate a rST file that can be
converted to a man page. From the root of the Linux repository, one
can generate and read the manual page with the following command:
$ ./scripts/bpf_doc.py helpers | rst2man | man -l -
(Note that the name of the script has changed since man-page commit
53666f6c3045.)
Given that the script is maintained in the Linux repository (it is run
through the BPF CI [2], and it is also used to generate a C header
that is shipped along with libbpf [3]), I would recommend against
copying it to the man-pages repository, so that we avoid getting two
copies out-of-sync. It is probably best to pick it up from the Linux
repo (since the UAPI header is also required anyway) when regenerating
the page.
If automation is not doable, I would be very happy to have someone
running this step before each project release.
Many thanks,
Quentin
[0] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/scripts/bpf_doc.py?h=v5.18
[1] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/uapi/linux/bpf.h?h=v5.18#n1526
[2] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/testing/selftests/bpf/Makefile.docs?h=v5.18
[3] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/lib/bpf/Makefile?h=v5.18#n159
