[PATCH 08/11] scripts/sphinx-build-wrapper: restore SPHINXOPTS parsing

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

While rewriting the wrapper, incidentally support for SPHINXOPTS
was dropped. Restore it and better handle them.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/Makefile       |  1 +
 scripts/sphinx-build-wrapper | 86 +++++++++++++++++++++++++++++-------
 2 files changed, 70 insertions(+), 17 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 280728cf78b9..d2e626627ee6 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -19,6 +19,7 @@ endif
 
 # You can set these variables from the command line.
 SPHINXBUILD   = sphinx-build
+SPHINXOPTS    =
 SPHINXDIRS    = .
 DOCS_THEME    =
 DOCS_CSS      =
diff --git a/scripts/sphinx-build-wrapper b/scripts/sphinx-build-wrapper
index 5c728956b53c..b9d40f4a6573 100755
--- a/scripts/sphinx-build-wrapper
+++ b/scripts/sphinx-build-wrapper
@@ -148,10 +148,10 @@ class SphinxBuilder:
 
         return path
 
-    def __init__(self, venv=None, verbose=False):
+    def __init__(self, venv=None, verbose=False, n_jobs=None):
         """Initialize internal variables"""
         self.venv = venv
-        self.verbose = verbose
+        self.verbose = None
 
         # Normal variables passed from Kernel's makefile
         self.kernelversion = os.environ.get("KERNELVERSION", "unknown")
@@ -159,6 +159,34 @@ class SphinxBuilder:
         self.pdflatex = os.environ.get("PDFLATEX", "xelatex")
         self.latexopts = os.environ.get("LATEXOPTS", "-interaction=batchmode -no-shell-escape")
 
+        if not verbose:
+            verbose = bool(os.environ.get("KBUILD_VERBOSE", "") != "")
+
+        # Handle SPHINXOPTS evironment
+        sphinxopts = shlex.split(os.environ.get("SPHINXOPTS", ""))
+
+        # As we handle number of jobs and quiet in separate, we need to pick
+        # it the same way as sphinx-build would pick, so let's use argparse
+        # do to the right argument expansion
+        parser = argparse.ArgumentParser()
+        parser.add_argument('-j', '--jobs', type=int)
+        parser.add_argument('-q', '--quiet', type=int)
+
+        # Other sphinx-build arguments go as-is, so place them
+        # at self.sphinxopts
+        sphinx_args, self.sphinxopts = parser.parse_known_args(sphinxopts)
+        if sphinx_args.quiet == True:
+            self.verbose = False
+
+        if sphinx_args.jobs:
+            self.n_jobs = sphinx_args.jobs
+
+        # Command line arguments was passed, override SPHINXOPTS
+        if verbose is not None:
+            self.verbose = verbose
+
+        self.n_jobs = n_jobs
+
         # Source tree directory. This needs to be at os.environ, as
         # Sphinx extensions and media uAPI makefile needs it
         self.srctree = os.environ.get("srctree")
@@ -199,7 +227,7 @@ class SphinxBuilder:
             else:
                 sys.exit(f"Venv {venv} not found.")
 
-    def run_sphinx(self, sphinx_build, sphinx_args, *args, **pwargs):
+    def run_sphinx(self, sphinx_build, build_args, *args, **pwargs):
         """
         Executes sphinx-build using current python3 command and setting
         -j parameter if possible to run the build in parallel.
@@ -207,11 +235,9 @@ class SphinxBuilder:
 
         with JobserverExec() as jobserver:
             if jobserver.claim:
-                parallelism = str(jobserver.claim)
+                n_jobs = str(jobserver.claim)
             else:
-                # As Sphinx has parallelism since version 1.7, we don't need
-                # any check here.
-                parallelism = "auto"
+                n_jobs = "auto" # Supported since Sphinx 1.7
 
             cmd = []
 
@@ -222,10 +248,19 @@ class SphinxBuilder:
 
             cmd.append(sphinx_build)
 
-            if parallelism:
-                cmd.append("-j" + parallelism)
+            # if present, SPHINXOPTS or command line --jobs overrides default
+            if self.n_jobs:
+                n_jobs = str(self.n_jobs)
 
-            cmd += sphinx_args
+            if n_jobs:
+                cmd += [f"-j{n_jobs}"]
+
+            if not self.verbose:
+                cmd.append("-q")
+
+            cmd += self.sphinxopts
+
+            cmd += build_args
 
             if self.verbose:
                 print(" ".join(cmd))
@@ -447,9 +482,6 @@ class SphinxBuilder:
 
             args.extend(["-D", f"latex_elements.papersize={paper}paper"])
 
-        if not self.verbose:
-            args.append("-q")
-
         if self.config_rust:
             args.extend(["-t", "rustdoc"])
 
@@ -582,6 +614,25 @@ class SphinxBuilder:
         except OSError as e:
             sys.exit(f"Failed to restart with {new_python_cmd}: {e}")
 
+def jobs_type(value):
+    """
+    Handle valid values for -j. Accepts Sphinx "-jauto", plus a number
+    equal or bigger than one.
+    """
+    if value is None:
+        return None
+
+    if value.lower() == 'auto':
+        return value.lower()
+
+    try:
+        if int(value) >= 1:
+            return value
+
+        raise argparse.ArgumentTypeError(f"Minimum jobs is 1, got {value}")
+    except ValueError:
+        raise argparse.ArgumentTypeError(f"Must be 'auto' or positive integer, got {value}")
+
 def main():
     """
     Main function. The only mandatory argument is the target. If not
@@ -607,18 +658,19 @@ def main():
     parser.add_argument("-v", "--verbose", action='store_true',
                         help="place build in verbose mode")
 
+    parser.add_argument('-j', '--jobs', type=jobs_type,
+                        help="Sets number of jobs to use with sphinx-build")
+
     parser.add_argument("-V", "--venv", nargs='?', const=f'{VENV_DEFAULT}',
                         default=None,
                         help=f'If used, run Sphinx from a venv dir (default dir: {VENV_DEFAULT})')
 
     args = parser.parse_args()
 
-    if not args.verbose:
-        args.verbose = bool(os.environ.get("KBUILD_VERBOSE", "") != "")
-
     SphinxBuilder.check_python()
 
-    builder = SphinxBuilder(venv=args.venv, verbose=args.verbose)
+    builder = SphinxBuilder(venv=args.venv, verbose=args.verbose,
+                            n_jobs=args.jobs)
 
     builder.build(args.target, sphinxdirs=args.sphinxdirs, conf=args.conf,
                   theme=args.theme, css=args.css, paper=args.paper)
-- 
2.50.1