Re: [PATCH] doc tools: better handle KBUILD_VERBOSE

[Mauro Carvalho Chehab]

On Fri, 27 Mar 2026 11:35:39 -0700
Jacob Keller <jacob.e.keller@xxxxxxxxx> wrote:

> On 3/26/2026 10:57 PM, Mauro Carvalho Chehab wrote:
> > As reported by Jacob, there are troubles when KBUILD_VERBOSE is
> > set at the environment.
> > 
> > Fix it on both kernel-doc and sphinx-build-wrapper.
> > 
> > Reported-by: Jacob Keller <jacob.e.keller@xxxxxxxxx>
> > Closes: https://lore.kernel.org/linux-doc/9367d899-53af-4d9c-9320-22fc4dbadca5@xxxxxxxxx/
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx>
> > ---  
> 
> I loaded this on my system and tested the build works as expected both
> with V=0 and when I export KBUILD_VERBOSE manually.
> 
> Thanks for fixing this quickly!
> 
> Tested-by: Jacob Keller <jacob.e.keller@xxxxxxxxx>
> 
> >  tools/docs/sphinx-build-wrapper     | 7 ++++++-
> >  tools/lib/python/kdoc/kdoc_files.py | 7 ++++++-
> >  2 files changed, 12 insertions(+), 2 deletions(-)
> > 
> > diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrapper
> > index 2c63d28f639d..1bb962202784 100755
> > --- a/tools/docs/sphinx-build-wrapper
> > +++ b/tools/docs/sphinx-build-wrapper
> > @@ -238,7 +238,12 @@ class SphinxBuilder:
> >              self.latexopts = os.environ.get("LATEXOPTS", "")
> >  
> >          if not verbose:
> > -            verbose = bool(os.environ.get("KBUILD_VERBOSE", "") != "")
> > +            try:
> > +                verbose = bool(int(os.environ.get("KBUILD_VERBOSE", 0)))
> > +            except ValueError:
> > +                # Handles an eventual case where verbosity is not a number
> > +                # like KBUILD_VERBOSE=""  
> 
> Strictly speaking I think os.environ.get() will handle the case of an
> empty KBUILD_VERBOSE by converting to the default value (in this case 0).

It won't. See:

	$ FOO="" python3
	Python 3.14.3 (main, Feb  4 2026, 00:00:00) [GCC 15.2.1 20260123 (Red Hat 15.2.1-7)] on linux
	Type "help", "copyright", "credits" or "license" for more information.
	>>> import os
	>>> os.environ.get("FOO", 0)
	''

	$ FOO="0" python3 
	Python 3.14.3 (main, Feb  4 2026, 00:00:00) [GCC 15.2.1 20260123 (Red Hat 15.2.1-7)] on linux
	Type "help", "copyright", "credits" or "license" for more information.
	>>> import os
	>>> os.environ.get("FOO", 0)
	... 
	'0'

	$ unset FOO; python3 
	Python 3.14.3 (main, Feb  4 2026, 00:00:00) [GCC 15.2.1 20260123 (Red Hat 15.2.1-7)] on linux
	Type "help", "copyright", "credits" or "license" for more information.
	>>> import os
	>>> os.environ.get("FOO", 0)
	... 
	0

it will only get an integer 0 if the env var (at the above example, FOO)
is not on env.

That's basically why we need to first convert it to integer than to
bool.

> The intent of the comment and code is pretty clear though, so I don't
> know that deserves a re-roll.

I opted to add a comment there because having two conversions,
first to int then to bool is not that obvious ;-)

Thanks,
Mauro