[PATCH] doc tools: better handle KBUILD_VERBOSE

[PATCH] doc tools: better handle KBUILD_VERBOSE

[Mauro Carvalho Chehab]

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@intel.com>
Closes: https://lore.kernel.org/linux-doc/9367d899-53af-4d9c-9320-22fc4dbadca5@intel.com/
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 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=""
+                verbose = False
 
         if verbose is not None:
             self.verbose = verbose
diff --git a/tools/lib/python/kdoc/kdoc_files.py b/tools/lib/python/kdoc/kdoc_files.py
index 2428cfc4e843..ed82b6e6ab25 100644
--- a/tools/lib/python/kdoc/kdoc_files.py
+++ b/tools/lib/python/kdoc/kdoc_files.py
@@ -238,7 +238,12 @@ class KernelFiles():
         """
 
         if not verbose:
-            verbose = bool(os.environ.get("KBUILD_VERBOSE", 0))
+            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=""
+                verbose = False
 
         if out_style is None:
             out_style = OutputFormat()
-- 
2.53.0

Re: [PATCH] doc tools: better handle KBUILD_VERBOSE

[Jacob Keller]

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@intel.com>
> Closes: https://lore.kernel.org/linux-doc/9367d899-53af-4d9c-9320-22fc4dbadca5@intel.com/
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---

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@intel.com>

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

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

Thanks,
Jake

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@intel.com> 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@intel.com>
> > Closes: https://lore.kernel.org/linux-doc/9367d899-53af-4d9c-9320-22fc4dbadca5@intel.com/
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > ---  
> 
> 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@intel.com>
> 
> >  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