Re: [PATCH bpf-next v2 1/2] scripts/bpf: Set version attribute for bpf-helpers(7) man page

[Alejandro Colomar <alx.manpages@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 3771 bytes --]

On 8/23/22 17:53, Quentin Monnet wrote:
> The bpf-helpers(7) manual page shipped in the man-pages project is
> generated from the documentation contained in the BPF UAPI header, in
> the Linux repository, parsed by script/bpf_doc.py and then fed to
> rst2man.
> 
> After a recent update of that page [0], Alejandro reported that the
> linter used to validate the man pages complains about the generated
> document [1]. The header for the page is supposed to contain some
> attributes that we do not set correctly with the script. This commit
> updates the "project and version" field. We discussed the format of
> those fields in [1] and [2].
> 
> Before:
> 
>      $ ./scripts/bpf_doc.py helpers | rst2man | grep '\.TH'
>      .TH BPF-HELPERS 7 "" "" ""
> 
> After:
> 
>      $ ./scripts/bpf_doc.py helpers | rst2man | grep '\.TH'
>      .TH BPF-HELPERS 7 "" "Linux v5.19-14022-g30d2a4d74e11" ""
> 
> We get the version from "git describe", but if unavailable, we fall back
> on "make kernelversion". If none works, for example because neither git
> nore make are installed, we just set the field to "Linux" and keep
> generating the page.
> 
> [0] https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/man7/bpf-helpers.7?id=19c7f78393f2b038e76099f87335ddf43a87f039
> [1] https://lore.kernel.org/all/20220823084719.13613-1-quentin@isovalent.com/t/#m58a418a318642c6428e14ce9bb84eba5183b06e8
> [2] https://lore.kernel.org/all/20220721110821.8240-1-alx.manpages@gmail.com/t/#m8e689a822e03f6e2530a0d6de9d128401916c5de
> 
> Cc: Alejandro Colomar <alx.manpages@gmail.com>
> Reported-by: Alejandro Colomar <alx.manpages@gmail.com>
> Signed-off-by: Quentin Monnet <quentin@isovalent.com>

Reviewed-by: Alejandro Colomar <alx.manpages@gmail.com>

> ---
>   scripts/bpf_doc.py | 21 ++++++++++++++++++++-
>   1 file changed, 20 insertions(+), 1 deletion(-)
> 
> diff --git a/scripts/bpf_doc.py b/scripts/bpf_doc.py
> index dfb260de17a8..061ad1dc3212 100755
> --- a/scripts/bpf_doc.py
> +++ b/scripts/bpf_doc.py
> @@ -10,6 +10,8 @@ from __future__ import print_function
>   import argparse
>   import re
>   import sys, os
> +import subprocess
> +
>   
>   class NoHelperFound(BaseException):
>       pass
> @@ -357,6 +359,20 @@ class PrinterRST(Printer):
>   
>           print('')
>   
> +    def get_kernel_version(self):
> +        try:
> +            version = subprocess.run(['git', 'describe'], cwd=linuxRoot,
> +                                     capture_output=True, check=True)
> +            version = version.stdout.decode().rstrip()
> +        except:
> +            try:
> +                version = subprocess.run(['make', 'kernelversion'], cwd=linuxRoot,
> +                                         capture_output=True, check=True)
> +                version = version.stdout.decode().rstrip()
> +            except:
> +                return 'Linux'
> +        return 'Linux {version}'.format(version=version)
> +
>   class PrinterHelpersRST(PrinterRST):
>       """
>       A printer for dumping collected information about helpers as a ReStructured
> @@ -378,6 +394,7 @@ list of eBPF helper functions
>   -------------------------------------------------------------------------------
>   
>   :Manual section: 7
> +:Version: {version}
>   
>   DESCRIPTION
>   ===========
> @@ -410,8 +427,10 @@ kernel at the top).
>   HELPERS
>   =======
>   '''
> +        kernelVersion = self.get_kernel_version()
> +
>           PrinterRST.print_license(self)
> -        print(header)
> +        print(header.format(version=kernelVersion))
>   
>       def print_footer(self):
>           footer = '''

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]