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

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

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

Hi Quentin,

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.
> 
> The man page should contain the date of last modification of the
> documentation. This commit adds the relevant date when generating the
> page.
> 
> Before:
> 
>      $ ./scripts/bpf_doc.py helpers | rst2man | grep '\.TH'
>      .TH BPF-HELPERS 7 "" "Linux v5.19-14022-g30d2a4d74e11" ""
> 
> After:
> 
>      $ ./scripts/bpf_doc.py helpers | rst2man | grep '\.TH'
>      .TH BPF-HELPERS 7 "2022-08-15" "Linux v5.19-14022-g30d2a4d74e11" ""
> 
> We get the version by using "git log" to look for the commit date of the
> latest change to the section of the BPF header containing the
> documentation. If the command fails, we just skip the date field. and
> keep generating the page.
> 
> 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 | 20 ++++++++++++++++++--
>   1 file changed, 18 insertions(+), 2 deletions(-)
> 
> diff --git a/scripts/bpf_doc.py b/scripts/bpf_doc.py
> index 061ad1dc3212..f4f3e7ec6d44 100755
> --- a/scripts/bpf_doc.py
> +++ b/scripts/bpf_doc.py
> @@ -12,6 +12,7 @@ import re
>   import sys, os
>   import subprocess
>   
> +helpersDocStart = 'Start of BPF helper function descriptions:'
>   
>   class NoHelperFound(BaseException):
>       pass
> @@ -235,7 +236,7 @@ class HeaderParser(object):
>           self.enum_syscalls = re.findall('(BPF\w+)+', bpf_cmd_str)
>   
>       def parse_desc_helpers(self):
> -        self.seek_to('* Start of BPF helper function descriptions:',
> +        self.seek_to(helpersDocStart,
>                        'Could not find start of eBPF helper descriptions list')
>           while True:
>               try:
> @@ -373,6 +374,17 @@ class PrinterRST(Printer):
>                   return 'Linux'
>           return 'Linux {version}'.format(version=version)
>   
> +    def get_last_doc_update(self, delimiter):
> +        try:
> +            cmd = ['git', 'log', '-1', '--pretty=format:%cs', '--no-patch',
> +                   '-L',
> +                   '/{}/,/\*\//:include/uapi/linux/bpf.h'.format(delimiter)]
> +            date = subprocess.run(cmd, cwd=linuxRoot,
> +                                  capture_output=True, check=True)
> +            return date.stdout.decode().rstrip()
> +        except:
> +            return ''
> +
>   class PrinterHelpersRST(PrinterRST):
>       """
>       A printer for dumping collected information about helpers as a ReStructured
> @@ -395,6 +407,7 @@ list of eBPF helper functions
>   
>   :Manual section: 7
>   :Version: {version}
> +{date_field}{date}
>   
>   DESCRIPTION
>   ===========
> @@ -428,9 +441,12 @@ HELPERS
>   =======
>   '''
>           kernelVersion = self.get_kernel_version()
> +        lastUpdate = self.get_last_doc_update(helpersDocStart)
>   
>           PrinterRST.print_license(self)
> -        print(header.format(version=kernelVersion))
> +        print(header.format(version=kernelVersion,
> +                            date_field = ':Date: ' if lastUpdate else '',
> +                            date=lastUpdate))
>   
>       def print_footer(self):
>           footer = '''

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

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