Better handle dependencies on Sphinx extensions
Subsystems (2)
Mauro Carvalho Chehab
maintainerv3 cover Better handle dependencies on Sphinx extensions
Sphinx has its own way to identify the need of rebuilding the documentation. It means that extensions need to use an internal API in order to notify about the need to consider other files.
The kerneldoc.py extension already does that, maintainers_include.py doesn't need (as it uses an API that internally does that), and kfigure.py does it on a different way. So, those are already safe.
However, other extensions don't notify nor implement their own checks, so, when a file that was parsed by them is changed, the corresponding documentation won't be rebuilt.
This series add support for it for ABI, features and kernel-include.
---
v3:
- Changed the meta-tag used when --enable-lineno and --enable-fname are used at the scripts that generate ReST output.
Mauro Carvalho Chehab (6):
scripts/get_feat.pl: allow output the parsed file names
docs: kernel_feat.py: add build dependencies
docs: kernel_abi.py: add sphinx build dependencies
docs: kernel_include.py: add sphinx build dependencies scripts/get_abi: change the file/line number meta info scripts/kernel-doc: change the line number meta info
Documentation/sphinx/kernel_abi.py | 6 +++++- Documentation/sphinx/kernel_feat.py | 20 ++++++++++++++++++-- Documentation/sphinx/kernel_include.py | 3 +++ Documentation/sphinx/kerneldoc.py | 2 +- scripts/get_abi.pl | 4 ++-- scripts/get_feat.pl | 11 +++++++++++ scripts/kernel-doc | 4 ++-- 7 files changed, 42 insertions(+), 8 deletions(-)
Signature · 1 line
2.35.1
Mauro Carvalho Chehab
maintainerPATCH v3 1/6 scripts/get_feat.pl: allow output the parsed file names
Such output could be helpful while debugging it, but its main goal is to tell kernel_feat.py about what files were used by the script. Thie way, kernel_feat.py can add those as documentation dependencies.
---
To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover. See [PATCH v3 0/6] at: https://lore.kernel.org/all/[email protected]/
scripts/get_feat.pl | 11 +++++++++++ 1 file changed, 11 insertions(+)
scripts/get_feat.pl +11 -0
@@ -13,6 +13,7 @@ my $man; my $debug; my $arch; my $feat; +my $enable_fname; my $basename = abs_path($0); $basename =~ s,/[^/]+$,/,;
@@ -31,6 +32,7 @@ GetOptions( 'arch=s' => \$arch, 'feat=s' => \$feat, 'feature=s' => \$feat, + "enable-fname" => \$enable_fname, man => \$man ) or pod2usage(2);
@@ -95,6 +97,10 @@ sub parse_feat { return if ($file =~ m,($prefix)/arch-support.txt,); return if (!($file =~ m,arch-support.txt$,)); + if ($enable_fname) { + printf ".. FILE %s\n", abs_path($file); + } + my $subsys = ""; $subsys = $2 if ( m,.*($prefix)/([^/]+).*,);
@@ -580,6 +586,11 @@ Output features for a single specific feature. Changes the location of the Feature files. By default, it uses the Documentation/features directory. +=item B<--enable-fname> + +Prints the file name of the feature files. This can be used in order to +track dependencies during documentation build. + =item B<--debug> Put the script in verbose mode, useful for debugging. Can be called multiple
Signature · 1 line
2.35.1
Mauro Carvalho Chehab
maintainerPATCH v3 2/6 docs: kernel_feat.py: add build dependencies
In reply to Mauro Carvalho ChehabEnsure that the feature files will be regenerated if any changes happen at the Documentation/features files that were processed by gen_feat.pl.
---
To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover. See [PATCH v3 0/6] at: https://lore.kernel.org/all/[email protected]/
Documentation/sphinx/kernel_feat.py | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-)
Documentation/sphinx/kernel_feat.py +18 -2
@@ -33,6 +33,7 @@ u""" import codecs import os +import re import subprocess import sys
@@ -82,7 +83,7 @@ class KernelFeat(Directive): env = doc.settings.env cwd = path.dirname(doc.current_source) - cmd = "get_feat.pl rest --dir " + cmd = "get_feat.pl rest --enable-fname --dir " cmd += self.arguments[0] if len(self.arguments) > 1:
@@ -102,7 +103,22 @@ class KernelFeat(Directive): shell_env["srctree"] = srctree lines = self.runCmd(cmd, shell=True, cwd=cwd, env=shell_env) - nodeList = self.nestedParse(lines, fname) + + line_regex = re.compile("^\.\. FILE (\S+)$") + + out_lines = "" + + for line in lines.split("\n"): + match = line_regex.search(line) + if match: + fname = match.group(1) + + # Add the file to Sphinx build dependencies + env.note_dependency(os.path.abspath(fname)) + else: + out_lines += line + "\n" + + nodeList = self.nestedParse(out_lines, fname) return nodeList def runCmd(self, cmd, **kwargs):
Signature · 1 line
2.35.1
Mauro Carvalho Chehab
maintainerPATCH v3 3/6 docs: kernel_abi.py: add sphinx build dependencies
In reply to Mauro Carvalho ChehabEnsure that Sphinx-build will handle the files parsed by get_abi.pl as dependencies. This way, if they are touched, the ABI output will be regenerated.
---
To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover. See [PATCH v3 0/6] at: https://lore.kernel.org/all/[email protected]/
Documentation/sphinx/kernel_abi.py | 4 ++++ 1 file changed, 4 insertions(+)
Documentation/sphinx/kernel_abi.py +4 -0
@@ -128,6 +128,7 @@ class KernelCmd(Directive): return out def nestedParse(self, lines, fname): + env = self.state.document.settings.env content = ViewList() node = nodes.section()
@@ -154,6 +155,9 @@ class KernelCmd(Directive): self.do_parse(content, node) content = ViewList() + # Add the file to Sphinx build dependencies + env.note_dependency(os.path.abspath(f)) + f = new_f # sphinx counts lines from 0
Signature · 1 line
2.35.1
Mauro Carvalho Chehab
maintainerPATCH v3 4/6 docs: kernel_include.py: add sphinx build dependencies
In reply to Mauro Carvalho ChehabThe files included by kernel-include should be added as build dependencies, in order for sphinx-build to rebuild the corresponding docs if any changes at the included file happens.
---
To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover. See [PATCH v3 0/6] at: https://lore.kernel.org/all/[email protected]/
Documentation/sphinx/kernel_include.py | 3 +++ 1 file changed, 3 insertions(+)
Documentation/sphinx/kernel_include.py +3 -0
@@ -59,6 +59,7 @@ class KernelInclude(Include): u"""KernelInclude (``kernel-include``) directive""" def run(self): + env = self.state.document.settings.env path = os.path.realpath( os.path.expandvars(self.arguments[0]))
@@ -70,6 +71,8 @@ class KernelInclude(Include): self.arguments[0] = path + env.note_dependency(os.path.abspath(path)) + #return super(KernelInclude, self).run() # won't work, see HINTs in _run() return self._run()
Signature · 1 line
2.35.1
Mauro Carvalho Chehab
maintainerPATCH v3 5/6 scripts/get_abi: change the file/line number meta info
In reply to Mauro Carvalho ChehabIn order to make it more standard and ReST compatible, change the meta-tag used with --enable-lineno from:
#define LINENO
to
.. LINENO
In practice, no functional changes.
---
To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover. See [PATCH v3 0/6] at: https://lore.kernel.org/all/[email protected]/
Documentation/sphinx/kernel_abi.py | 2 +- scripts/get_abi.pl | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-)
Documentation/sphinx/kernel_abi.py +1 -1
@@ -138,7 +138,7 @@ class KernelCmd(Directive): code_block += "\n " + l lines = code_block + "\n\n" - line_regex = re.compile("^#define LINENO (\S+)\#([0-9]+)$") + line_regex = re.compile("^\.\. LINENO (\S+)\#([0-9]+)$") ln = 0 n = 0 f = fname
scripts/get_abi.pl +2 -2
@@ -327,7 +327,7 @@ sub output_rest { my @filepath = split / /, $data{$what}->{filepath}; if ($enable_lineno) { - printf "#define LINENO %s%s#%s\n\n", + printf ".. LINENO %s%s#%s\n\n", $prefix, $file[0], $data{$what}->{line_no}; }
@@ -1023,7 +1023,7 @@ logic (B<--no-rst-source>). =item B<--enable-lineno> -Enable output of #define LINENO lines. +Enable output of .. LINENO lines. =item B<--debug> I<debug level>
Signature · 1 line
2.35.1
Mauro Carvalho Chehab
maintainerPATCH v3 6/6 scripts/kernel-doc: change the line number meta info
In reply to Mauro Carvalho ChehabIn order to make it more standard and ReST compatible, change the meta-tag used with --enable-lineno from:
#define LINENO
to
.. LINENO
In practice, no functional changes.
---
To avoid mailbombing on a large number of people, only mailing lists were C/C on the cover. See [PATCH v3 0/6] at: https://lore.kernel.org/all/[email protected]/
Documentation/sphinx/kerneldoc.py | 2 +- scripts/kernel-doc | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-)
Documentation/sphinx/kerneldoc.py +1 -1
@@ -130,7 +130,7 @@ class KernelDocDirective(Directive): result = ViewList() lineoffset = 0; - line_regex = re.compile("^#define LINENO ([0-9]+)$") + line_regex = re.compile("^\.\. LINENO ([0-9]+)$") for line in lines: match = line_regex.search(line) if match:
scripts/kernel-doc +2 -2
@@ -424,7 +424,7 @@ sub get_kernel_version() { sub print_lineno { my $lineno = shift; if ($enable_lineno && defined($lineno)) { - print "#define LINENO " . $lineno . "\n"; + print ".. LINENO " . $lineno . "\n"; } } ##
@@ -2478,7 +2478,7 @@ May be specified multiple times. =item -enable-lineno -Enable output of #define LINENO lines. +Enable output of .. LINENO lines. =back
Signature · 1 line
2.35.1
Jonathan Corbet
maintainerQuoted 8 lines · Mauro Carvalho Chehab
Sphinx has its own way to identify the need of rebuilding the documentation. It means that extensions need to use an internal API in order to notify about the need to consider other files.
The
kerneldoc.pyextension already does that,maintainers_include.pydoesn't need (as it uses an API that internally does that), andkfigure.pydoes it on a different way. So, those are already safe.
Quoted 5 lines
However, other extensions don't notify nor implement their own checks, so, when a file that was parsed by them is changed, the corresponding documentation won't be rebuilt.
This series add support for it for ABI, features and kernel-include.
Series applied, thanks.
jon