| Message ID | 20220823155327.98888-2-quentin@isovalent.com (mailing list archive) |
|---|---|
| State | Accepted |
| Commit | 92ec1cc3784a2a8a7a62596dcec4f2224b85dcf4 |
| Delegated to: | BPF |
| Headers | show |
| Series | [bpf-next,v2,1/2] scripts/bpf: Set version attribute for bpf-helpers(7) man page | expand |
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 = '''
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 = '''
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(-)