Passing SPHINXOPTS is broken

Passing SPHINXOPTS is broken

[Jani Nikula]

I was trying to get the regular sphinx-build output.

The monster sphinx-build-wrapper thing has this obnoxious and complex
logic of forcing -q unless you specify verbose in SPHINXOPTS. You'd
think those defaults should be specified in the Makefile. But no.

Anyway, setting SPHINXOPTS in the environment or on the make
command-line doesn't work, because Documentation/Makefile overrides it
to empty.


BR,
Jani.

-- 
Jani Nikula, Intel

Re: Passing SPHINXOPTS is broken

[Jani Nikula]

On Fri, 23 Jan 2026, Jani Nikula <jani.nikula@intel.com> wrote:
> I was trying to get the regular sphinx-build output.
>
> The monster sphinx-build-wrapper thing has this obnoxious and complex
> logic of forcing -q unless you specify verbose in SPHINXOPTS. You'd
> think those defaults should be specified in the Makefile. But no.
>
> Anyway, setting SPHINXOPTS in the environment or on the make
> command-line doesn't work, because Documentation/Makefile overrides it
> to empty.

Oh, it's more sad than just this. There is no way to use SPHINXOPTS to
get sphinx-build to produce the regular non-quiet output (that the
wrapper calls verbose).

You have to use KBUILD_VERBOSE to make the damn wrapper not pass -q to
sphinx-build. The wrapper appends the -q overwriting anything the user
might want to pass on SPHINXOPTS. Which can't be passed anyway because
the Makefile overwrites it.

-- 
Jani Nikula, Intel

Re: Passing SPHINXOPTS is broken

[Mauro Carvalho Chehab]

On Fri, 23 Jan 2026 13:06:51 +0200
Jani Nikula <jani.nikula@intel.com> wrote:

> On Fri, 23 Jan 2026, Jani Nikula <jani.nikula@intel.com> wrote:
> > I was trying to get the regular sphinx-build output.

Just do:

	$ make V=1 htmldocs

or:
	$ ./tools/docs/sphinx-build-wrapper -v htmldocs

> > The monster sphinx-build-wrapper thing has this obnoxious and complex
> > logic of forcing -q unless you specify verbose in SPHINXOPTS. You'd
> > think those defaults should be specified in the Makefile. But no.

It is like there to mimic what we used to have at Makefile.

> > Anyway, setting SPHINXOPTS in the environment or on the make
> > command-line doesn't work, because Documentation/Makefile overrides it
> > to empty.  
> 
> Oh, it's more sad than just this. There is no way to use SPHINXOPTS to
> get sphinx-build to produce the regular non-quiet output (that the
> wrapper calls verbose).
>
> You have to use KBUILD_VERBOSE to make the damn wrapper not pass -q to
> sphinx-build. 

KBUILD_VERBOSE is the Makefile's env var that handles V=1.

>The wrapper appends the -q overwriting anything the user
> might want to pass on SPHINXOPTS. Which can't be passed anyway because
> the Makefile overwrites it.

It is like there to mimic what we used to have at Makefile: it was
was always passing "-q", except when called with V=1.

Thanks,
Mauro

Re: Passing SPHINXOPTS is broken

[Jani Nikula]

On Fri, 23 Jan 2026, Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> On Fri, 23 Jan 2026 13:06:51 +0200
> Jani Nikula <jani.nikula@intel.com> wrote:
>
>> On Fri, 23 Jan 2026, Jani Nikula <jani.nikula@intel.com> wrote:
>> > I was trying to get the regular sphinx-build output.
>
> Just do:
>
> 	$ make V=1 htmldocs
>
> or:
> 	$ ./tools/docs/sphinx-build-wrapper -v htmldocs
>
>> > The monster sphinx-build-wrapper thing has this obnoxious and complex
>> > logic of forcing -q unless you specify verbose in SPHINXOPTS. You'd
>> > think those defaults should be specified in the Makefile. But no.
>
> It is like there to mimic what we used to have at Makefile.
>
>> > Anyway, setting SPHINXOPTS in the environment or on the make
>> > command-line doesn't work, because Documentation/Makefile overrides it
>> > to empty.  
>> 
>> Oh, it's more sad than just this. There is no way to use SPHINXOPTS to
>> get sphinx-build to produce the regular non-quiet output (that the
>> wrapper calls verbose).
>>
>> You have to use KBUILD_VERBOSE to make the damn wrapper not pass -q to
>> sphinx-build. 
>
> KBUILD_VERBOSE is the Makefile's env var that handles V=1.
>
>>The wrapper appends the -q overwriting anything the user
>> might want to pass on SPHINXOPTS. Which can't be passed anyway because
>> the Makefile overwrites it.
>
> It is like there to mimic what we used to have at Makefile: it was
> was always passing "-q", except when called with V=1.

I don't want verbose output from e.g. kernel-doc saying "Scanning doc
for function" bla bla blaa, but I do want the regular Sphinx messages on
what phase of the build it's at.

There doesn't seem to be a way to get the regular Sphinx "not quiet, not
verbose" output, without also going verbose on silly kernel-doc
messages.


BR,
Jani.

-- 
Jani Nikula, Intel

Re: Passing SPHINXOPTS is broken

[Mauro Carvalho Chehab]

On Fri, 23 Jan 2026 15:47:30 +0200
Jani Nikula <jani.nikula@intel.com> wrote:

> On Fri, 23 Jan 2026, Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> > On Fri, 23 Jan 2026 13:06:51 +0200
> > Jani Nikula <jani.nikula@intel.com> wrote:
> >  
> >> On Fri, 23 Jan 2026, Jani Nikula <jani.nikula@intel.com> wrote:  
> >> > I was trying to get the regular sphinx-build output.  
> >
> > Just do:
> >
> > 	$ make V=1 htmldocs
> >
> > or:
> > 	$ ./tools/docs/sphinx-build-wrapper -v htmldocs
> >  
> >> > The monster sphinx-build-wrapper thing has this obnoxious and complex
> >> > logic of forcing -q unless you specify verbose in SPHINXOPTS. You'd
> >> > think those defaults should be specified in the Makefile. But no.  
> >
> > It is like there to mimic what we used to have at Makefile.
> >  
> >> > Anyway, setting SPHINXOPTS in the environment or on the make
> >> > command-line doesn't work, because Documentation/Makefile overrides it
> >> > to empty.    
> >> 
> >> Oh, it's more sad than just this. There is no way to use SPHINXOPTS to
> >> get sphinx-build to produce the regular non-quiet output (that the
> >> wrapper calls verbose).
> >>
> >> You have to use KBUILD_VERBOSE to make the damn wrapper not pass -q to
> >> sphinx-build.   
> >
> > KBUILD_VERBOSE is the Makefile's env var that handles V=1.
> >  
> >>The wrapper appends the -q overwriting anything the user
> >> might want to pass on SPHINXOPTS. Which can't be passed anyway because
> >> the Makefile overwrites it.  
> >
> > It is like there to mimic what we used to have at Makefile: it was
> > was always passing "-q", except when called with V=1.  
> 
> I don't want verbose output from e.g. kernel-doc saying "Scanning doc
> for function" bla bla blaa, but I do want the regular Sphinx messages on
> what phase of the build it's at.
> 
> There doesn't seem to be a way to get the regular Sphinx "not quiet, not
> verbose" output, without also going verbose on silly kernel-doc
> messages.

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.

Regards,
Mauro

Re: Passing SPHINXOPTS is broken

[Jani Nikula]

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.

BR,
Jani.

-- 
Jani Nikula, Intel

Re: Passing SPHINXOPTS is broken

[Mauro Carvalho Chehab]

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.

What we could do is to add something like this:

	diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrapper
	index 7a5fcef25429..13731b478822 100755
	--- a/tools/docs/sphinx-build-wrapper
	+++ b/tools/docs/sphinx-build-wrapper
	@@ -165,6 +165,7 @@ class SphinxBuilder:
	         parser = argparse.ArgumentParser()
	         parser.add_argument('-j', '--jobs', type=int)
	         parser.add_argument('-q', '--quiet', action='store_true')
	+        parser.add_argument('-n', '--not-quiet', action='store_true')
 
	         #
	         # Other sphinx-build arguments go as-is, so place them
	@@ -181,6 +182,9 @@ class SphinxBuilder:
	         if sphinx_args.quiet is True:
	             verbose = False
	 
	+        if sphinx_args.not_quiet is True:
	+            verbose = True
	+
	         #
	         # If the user explicitly sets "-j" at command line, use it.
	         # Otherwise, pick it from SPHINXOPTS args

Regards,
Mauro

Re: Passing SPHINXOPTS is broken

[Mauro Carvalho Chehab]

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):