Re: Passing SPHINXOPTS is broken

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

On Fri, 23 Jan 2026 16:09:33 +0100
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:

> On Fri, 23 Jan 2026 16:28:37 +0200
> Jani Nikula <jani.nikula@intel.com> wrote:
> 
> > On Fri, 23 Jan 2026, Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:  
> > > With Makefile, there isn't. This didn't change: it is just the same
> > > behavior we used to have before the wrapper addition, after this
> > > changeset (merged in 2022):
> > >
> > > 	c0d3b83100c8 ("kbuild: do not print extra logs for V=2")
> > >
> > > Now, currently it is possible to do that by calling the wrapper
> > > directly:
> > >
> > > 	$ ./tools/docs/sphinx-build-wrapper -v htmldocs --sphinxdirs peci
> > >
> > > Here, "-v" instructs the wrapper to drop "-q" flag, but doesn't touch
> > > KBUILD_VERBOSE, so you won't see kernel-doc debug messages.    
> > 
> > I'm not really interested in using the wrapper directly. I use make O=
> > builds, and I don't want to and I should not have to figure out how to
> > do that with the wrapper.
> > 
> > Again, it should be possible to pass user SPHINXOPTS to sphinx-build.  
> 
> Agreed, but the problem is that, since a long time, "-q" was always 
> aways added when V=0, and we don't have V=2 for docs anymore.
> 
> Unfortunately, Sphinx doesn't have a --no-quiet option. So, right now it
> preserves the behavior it had for a long time:
> 
> - if V=0, defaults to "-q"
> - if V=1, defaults to not use "-q", but one can add SPHINXOPTS=-q
>   to keep Sphinx build in quiet mode.

Forgot to mention, but there's an obvious alternative: change the default
to not be quiet, e.g.:

	diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrapper
	index 78ff7ac202ef..76f14101d134 100755
	--- a/tools/docs/sphinx-build-wrapper
	+++ b/tools/docs/sphinx-build-wrapper
	@@ -179,7 +179,7 @@ class SphinxBuilder:
	         # Build a list of sphinx args, honoring verbosity here if specified
	         #
 
	-        verbose = self.verbose
	+        verbose = True
	         sphinx_args, self.sphinxopts = parser.parse_known_args(sphinxopts)
	         if sphinx_args.quiet is True:
	             verbose = False

This will change the behavior that we had since 2022 (at least), causing
sphinx-build to always show its progress.

From my side, I'm perfectly fine with that, but it might cause side
effects for CI. That's basically why I opted to preserve the original
behavior.

Yet, after thinking more carefully about that, IMO the best would
be to use the "-v" argument, preserving the current behavior, but
allowing it to be overridden using "-v".

See the patch below.

Regards,
Mauro


[PATCH] docs: sphinx-build-wrapper: allow -v override -q

Documentation builds were using "-q" for a long time, but sometimes
it is nice to see the Sphinx progress, without increasing build
verbosity - which would also turn on kernel-doc verbosity.

Instead of doing that, let's parse the sphinx-build already-existing
-v: each time it is used, it increases the verbosity level.

With that, if the default is to use -q, a single -v will disable
quiet mode. Passing more -v will keep increasing its verbosity.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrapper
index 78ff7ac202ef..8080ace60680 100755
--- a/tools/docs/sphinx-build-wrapper
+++ b/tools/docs/sphinx-build-wrapper
@@ -168,6 +168,7 @@ class SphinxBuilder:
         parser = argparse.ArgumentParser()
         parser.add_argument('-j', '--jobs', type=int)
         parser.add_argument('-q', '--quiet', action='store_true')
+        parser.add_argument('-v', '--verbose', default=0, action='count')
 
         #
         # Other sphinx-build arguments go as-is, so place them
@@ -179,10 +180,14 @@ class SphinxBuilder:
         # Build a list of sphinx args, honoring verbosity here if specified
         #
 
-        verbose = self.verbose
         sphinx_args, self.sphinxopts = parser.parse_known_args(sphinxopts)
+
+        verbose = sphinx_args.verbose
+        if self.verbose:
+            verbose += 1
+
         if sphinx_args.quiet is True:
-            verbose = False
+            verbose = 0
 
         #
         # If the user explicitly sets "-j" at command line, use it.
@@ -195,8 +200,11 @@ class SphinxBuilder:
         else:
             self.n_jobs = None
 
-        if not verbose:
+        if verbose < 1:
             self.sphinxopts += ["-q"]
+        else:
+            for i in range(1, sphinx_args.verbose):
+                self.sphinxopts += ["-v"]
 
     def __init__(self, builddir, venv=None, verbose=False, n_jobs=None,
                  interactive=None):