Re: Passing SPHINXOPTS is broken

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

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