Skip to contentSkip to conversation

Better handle dependencies on Sphinx extensions

PATCH In review Mauro Carvalho Chehab 2 participants 8 messages Mar 26, 2022 – Mar 28, 2022

Subsystems (2)
lore
Share & tools
lore

Mauro Carvalho Chehab

author maintainer
#0 lore raw

v3 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
author maintainer
#1 lore raw

PATCH 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
index 457712355676..76cfb96b59b6 100755
@@ -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
author maintainer
#2 lore raw

PATCH v3 2/6 docs: kernel_feat.py: add build dependencies

In reply to Mauro Carvalho Chehab

Ensure 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
index 8138d69a6987..27b701ed3681 100644
@@ -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
author maintainer
#3 lore raw

PATCH v3 3/6 docs: kernel_abi.py: add sphinx build dependencies

In reply to Mauro Carvalho Chehab

Ensure 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
index 4392b3cb4020..efab9b14a9f5 100644
@@ -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
author maintainer
#4 lore raw

PATCH v3 4/6 docs: kernel_include.py: add sphinx build dependencies

In reply to Mauro Carvalho Chehab

The 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
index f523aa68a36b..abe768088377 100755
@@ -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
author maintainer
#5 lore raw

PATCH v3 5/6 scripts/get_abi: change the file/line number meta info

In reply to Mauro Carvalho Chehab

In 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
index efab9b14a9f5..b5feb5b1d905 100644
@@ -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
index 7437e19ba3ac..1389db76cff3 100755
@@ -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
author maintainer
#6 lore raw

PATCH v3 6/6 scripts/kernel-doc: change the line number meta info

In reply to Mauro Carvalho Chehab

In 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
index 8189c33b9dda..9395892c7ba3 100644
@@ -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
index 9c084a2ba3b0..7516949bb049 100755
@@ -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
maintainer
#7 lore raw
In reply to Mauro Carvalho Chehab
Quoted 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.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.

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