* [PATCH bpf-next v2 2/2] scripts/bpf: Set date attribute for bpf-helpers(7) man page
2022-08-23 15:53 [PATCH bpf-next v2 1/2] scripts/bpf: Set version attribute for bpf-helpers(7) man page Quentin Monnet
@ 2022-08-23 15:53 ` Quentin Monnet
2022-08-23 16:54 ` Alejandro Colomar
2022-08-23 16:55 ` [PATCH bpf-next v2 1/2] scripts/bpf: Set version " Alejandro Colomar
2022-08-23 21:00 ` patchwork-bot+netdevbpf
2 siblings, 1 reply; 5+ messages in thread
From: Quentin Monnet @ 2022-08-23 15:53 UTC (permalink / raw)
To: Alexei Starovoitov, Daniel Borkmann, Andrii Nakryiko
Cc: Martin KaFai Lau, Song Liu, Yonghong Song, John Fastabend,
KP Singh, Stanislav Fomichev, Hao Luo, Jiri Olsa, bpf,
Quentin Monnet, Alejandro Colomar
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>
---
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 = '''
--
2.25.1
^ permalink raw reply related [flat|nested] 5+ messages in thread* Re: [PATCH bpf-next v2 2/2] scripts/bpf: Set date attribute for bpf-helpers(7) man page
2022-08-23 15:53 ` [PATCH bpf-next v2 2/2] scripts/bpf: Set date " Quentin Monnet
@ 2022-08-23 16:54 ` Alejandro Colomar
0 siblings, 0 replies; 5+ messages in thread
From: Alejandro Colomar @ 2022-08-23 16:54 UTC (permalink / raw)
To: Quentin Monnet, Alexei Starovoitov, Daniel Borkmann,
Andrii Nakryiko
Cc: Martin KaFai Lau, Song Liu, Yonghong Song, John Fastabend,
KP Singh, Stanislav Fomichev, Hao Luo, Jiri Olsa, bpf
[-- 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 --]
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH bpf-next v2 1/2] scripts/bpf: Set version attribute for bpf-helpers(7) man page
2022-08-23 15:53 [PATCH bpf-next v2 1/2] scripts/bpf: Set version attribute for bpf-helpers(7) man page Quentin Monnet
2022-08-23 15:53 ` [PATCH bpf-next v2 2/2] scripts/bpf: Set date " Quentin Monnet
@ 2022-08-23 16:55 ` Alejandro Colomar
2022-08-23 21:00 ` patchwork-bot+netdevbpf
2 siblings, 0 replies; 5+ messages in thread
From: Alejandro Colomar @ 2022-08-23 16:55 UTC (permalink / raw)
To: Quentin Monnet, Alexei Starovoitov, Daniel Borkmann,
Andrii Nakryiko
Cc: Martin KaFai Lau, Song Liu, Yonghong Song, John Fastabend,
KP Singh, Stanislav Fomichev, Hao Luo, Jiri Olsa, bpf
[-- 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 --]
^ permalink raw reply [flat|nested] 5+ messages in thread* Re: [PATCH bpf-next v2 1/2] scripts/bpf: Set version attribute for bpf-helpers(7) man page
2022-08-23 15:53 [PATCH bpf-next v2 1/2] scripts/bpf: Set version attribute for bpf-helpers(7) man page Quentin Monnet
2022-08-23 15:53 ` [PATCH bpf-next v2 2/2] scripts/bpf: Set date " Quentin Monnet
2022-08-23 16:55 ` [PATCH bpf-next v2 1/2] scripts/bpf: Set version " Alejandro Colomar
@ 2022-08-23 21:00 ` patchwork-bot+netdevbpf
2 siblings, 0 replies; 5+ messages in thread
From: patchwork-bot+netdevbpf @ 2022-08-23 21:00 UTC (permalink / raw)
To: Quentin Monnet
Cc: ast, daniel, andrii, kafai, songliubraving, yhs, john.fastabend,
kpsingh, sdf, haoluo, jolsa, bpf, alx.manpages
Hello:
This series was applied to bpf/bpf-next.git (master)
by Daniel Borkmann <daniel@iogearbox.net>:
On Tue, 23 Aug 2022 16:53:26 +0100 you 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].
>
> [...]
Here is the summary with links:
- [bpf-next,v2,1/2] scripts/bpf: Set version attribute for bpf-helpers(7) man page
https://git.kernel.org/bpf/bpf-next/c/fd0a38f9c37d
- [bpf-next,v2,2/2] scripts/bpf: Set date attribute for bpf-helpers(7) man page
https://git.kernel.org/bpf/bpf-next/c/92ec1cc3784a
You are awesome, thank you!
--
Deet-doot-dot, I am a bot.
https://korg.docs.kernel.org/patchwork/pwbot.html
^ permalink raw reply [flat|nested] 5+ messages in thread