[PATCH v2 23/32] scripts: kernel-doc: allow passing desired Sphinx C domain dialect

[Paolo Bonzini]

From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

When kernel-doc is called via kerneldoc.py, there's no need to
auto-detect the Sphinx version, as the Sphinx module already
knows it. So, add an optional parameter to allow changing the
Sphinx dialect.

As kernel-doc can also be manually called, keep the auto-detection
logic if the parameter was not specified. On such case, emit
a warning if sphinx-build can't be found at PATH.

I ended using a suggestion from Joe for using a more readable
regex, instead of using a complex one with a hidden group like:

        m/^(\d+)\.(\d+)(?:\.?(\d+)?)/

in order to get the optional <patch> argument.

Thanks-to: Joe Perches <joe@perches.com>
Suggested-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Message-Id: <20201117165312.118257-23-pbonzini@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
---
 docs/sphinx/kerneldoc.py |  5 ++++
 scripts/kernel-doc       | 51 +++++++++++++++++++++++++++++++++-------
 2 files changed, 48 insertions(+), 8 deletions(-)

diff --git a/docs/sphinx/kerneldoc.py b/docs/sphinx/kerneldoc.py
index c0180e02a2..079aadced3 100644
--- a/docs/sphinx/kerneldoc.py
+++ b/docs/sphinx/kerneldoc.py
@@ -69,6 +69,11 @@ class KernelDocDirective(Directive):
         env = self.state.document.settings.env
         cmd = env.config.kerneldoc_bin + ['-rst', '-enable-lineno']
 
+        # Pass the version string to kernel-doc, as it needs to use a different
+        # dialect, depending what the C domain supports for each specific
+        # Sphinx versions
+        cmd += ['-sphinx-version', sphinx.__version__]
+
         filename = env.config.kerneldoc_srctree + '/' + self.arguments[0]
         export_file_patterns = []
 
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 478037f736..667ad3169c 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -56,6 +56,13 @@ Output format selection (mutually exclusive):
   -rst                 Output reStructuredText format.
   -none                        Do not output documentation, only warnings.
 
+Output format selection modifier (affects only ReST output):
+
+  -sphinx-version      Use the ReST C domain dialect compatible with an
+                       specific Sphinx Version.
+                       If not specified, kernel-doc will auto-detect using
+                       the sphinx-build version found on PATH.
+
 Output selection (mutually exclusive):
   -export              Only output documentation for symbols that have been
                        exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
@@ -270,7 +277,7 @@ if ($#ARGV == -1) {
 }
 
 my $kernelversion;
-my $sphinx_major;
+my ($sphinx_major, $sphinx_minor, $sphinx_patch);
 
 my $dohighlight = "";
 
@@ -457,6 +464,23 @@ while ($ARGV[0] =~ m/^--?(.*)/) {
            $enable_lineno = 1;
     } elsif ($cmd eq 'show-not-found') {
        $show_not_found = 1;  # A no-op but don't fail
+    } elsif ($cmd eq "sphinx-version") {
+       my $ver_string = shift @ARGV;
+       if ($ver_string =~ m/^(\d+)(\.\d+)?(\.\d+)?/) {
+           $sphinx_major = $1;
+           if (defined($2)) {
+               $sphinx_minor = substr($2,1);
+           } else {
+               $sphinx_minor = 0;
+           }
+           if (defined($3)) {
+               $sphinx_patch = substr($3,1)
+           } else {
+               $sphinx_patch = 0;
+           }
+       } else {
+           die "Sphinx version should either major.minor or major.minor.patch 
format\n";
+       }
     } else {
        # Unknown argument
         usage();
@@ -477,29 +501,37 @@ sub findprog($)
 sub get_sphinx_version()
 {
        my $ver;
-       my $major = 1;
 
        my $cmd = "sphinx-build";
        if (!findprog($cmd)) {
                my $cmd = "sphinx-build3";
-               return $major if (!findprog($cmd));
+               if (!findprog($cmd)) {
+                       $sphinx_major = 1;
+                       $sphinx_minor = 2;
+                       $sphinx_patch = 0;
+                       printf STDERR "Warning: Sphinx version not found. Using 
default (Sphinx version %d.%d.%d)\n",
+                              $sphinx_major, $sphinx_minor, $sphinx_patch;
+                       return;
+               }
        }
 
        open IN, "$cmd --version 2>&1 |";
        while (<IN>) {
                if (m/^\s*sphinx-build\s+([\d]+)\.([\d\.]+)(\+\/[\da-f]+)?$/) {
-                       $major=$1;
+                       $sphinx_major = $1;
+                       $sphinx_minor = $2;
+                       $sphinx_patch = $3;
                        last;
                }
                # Sphinx 1.2.x uses a different format
                if (m/^\s*Sphinx.*\s+([\d]+)\.([\d\.]+)$/) {
-                       $major=$1;
+                       $sphinx_major = $1;
+                       $sphinx_minor = $2;
+                       $sphinx_patch = $3;
                        last;
                }
        }
        close IN;
-
-       return $major;
 }
 
 # get kernel version from env
@@ -2333,7 +2365,10 @@ sub process_file($) {
 }
 
 
-$sphinx_major = get_sphinx_version();
+if ($output_mode eq "rst") {
+       get_sphinx_version() if (!$sphinx_major);
+}
+
 $kernelversion = get_kernel_version();
 
 # generate a sequence of code that will splice in highlighting information
-- 
2.26.2