Re: kernel-doc overly verbose with V=0

[Mauro Carvalho Chehab]

On Tue, 24 Mar 2026 13:37:39 -0700
Jacob Keller <jacob.e.keller@xxxxxxxxx> wrote:

> Hi,
> 
> I recently saw some strange behavior with the Python kernel-doc. I was
> seeing the verbose info lines from the kernel-doc script, i.e.:
> 
> > Info: ice_ptp_hw.c:5377 Scanning doc for function ice_cgu_get_pin_freq_supp
> > Info: ice_ptp_hw.c:5406 Scanning doc for function ice_cgu_get_pin_name
> > Info: ice_ptp_hw.c:5441 Scanning doc for function ice_cgu_state_to_name
> > Info: ice_ptp_hw.c:5463 Scanning doc for function ice_get_dpll_ref_sw_status
> > Info: ice_ptp_hw.c:5505 Scanning doc for function ice_set_dpll_ref_sw_status
> > Info: ice_ptp_hw.c:5544 Scanning doc for function ice_get_cgu_state
> > Info: ice_ptp_hw.c:5612 Scanning doc for function ice_get_cgu_rclk_pin_info
> > Info: ice_ptp_hw.c:5671 Scanning doc for function ice_cgu_get_output_pin_state_caps
> > Info: ice_ptp_hw.c:5733 Scanning doc for function ice_ptp_lock
> > Info: ice_ptp_hw.c:5770 Scanning doc for function ice_ptp_unlock
> > Info: ice_ptp_hw.c:5782 Scanning doc for function ice_ptp_init_hw
> > Info: ice_ptp_hw.c:5811 Scanning doc for function ice_ptp_write_port_cmd
> > Info: ice_ptp_hw.c:5834 Scanning doc for function ice_ptp_one_port_cmd
> > Info: ice_ptp_hw.c:5866 Scanning doc for function ice_ptp_port_cmd
> > Info: ice_ptp_hw.c:5901 Scanning doc for function ice_ptp_tmr_cmd
> > Info: ice_ptp_hw.c:5934 Scanning doc for function ice_ptp_init_time
> > Info: ice_ptp_hw.c:5986 Scanning doc for function ice_ptp_write_incval
> > Info: ice_ptp_hw.c:6035 Scanning doc for function ice_ptp_write_incval_locked
> > Info: ice_ptp_hw.c:6056 Scanning doc for function ice_ptp_adj_clock
> > Info: ice_ptp_hw.c:6107 Scanning doc for function ice_read_phy_tstamp
> > Info: ice_ptp_hw.c:6134 Scanning doc for function ice_clear_phy_tstamp
> > Info: ice_ptp_hw.c:6164 Scanning doc for function ice_ptp_reset_ts_memory
> > Info: ice_ptp_hw.c:6183 Scanning doc for function ice_ptp_init_phc
> > Info: ice_ptp_hw.c:6215 Scanning doc for function ice_get_phy_tx_tstamp_ready
> > Info: ice_ptp_hw.c:6247 Scanning doc for function ice_check_phy_tx_tstamp_ready
> > Info: ice_ptp_hw.c:6273 Scanning doc for function ice_ptp_config_sfd
> > Info: ice_ptp_hw.c:6293 Scanning doc for function refsync_pin_id_valid  
> 
> I didn't understand why I was seeing this as it should only be happening
> if running kernel-doc in verbose mode. Then I discovered I had set
> KBUILD_VERBOSE=0 in my environment.
> 
> The python kernel-doc implementation reads this in the __init__ for
> KernelFiles() on line 165:
> 
> >         if not verbose:
> >             verbose = bool(os.environ.get("KBUILD_VERBOSE", 0))  
> 
> After some debugging, I realized this reads KBUILD_VERBOSE as a string,
> then converts it to a boolean using python's standard rules, so "0"
> becomes true, which enables the verbose output.

Looking at tools/docs/sphinx-build-wrapper, it implements verbosity
by doing:

	verbose = bool(os.environ.get("KBUILD_VERBOSE", "") != "")

which will also have the same problem as the one you detected.

Perhaps the right fix would be to first convert to int then to bool
on both places, in a way that "" will also be handled properly.
Perhaps with:

	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

> This is in contrast to the (now removed) kernel-doc.pl script which
> checked the value for a 1:
> 
> >  if (defined($ENV{'KBUILD_VERBOSE'}) && $ENV{'KBUILD_VERBOSE'} =~ '1')   
> The same behavior happens if you assign V=0 on the command line or to
> any other non-empty string, since when V is set on the command line it
> sets KBUILD_VERBOSE.

That's funny... we did test make V=0 htmldocs / make V=1 htmldocs 

It sounds that the problem is only if you explicitly set it without
relying on gnu make.

> Of course, I can remove KBUILD_VERBOSE from my environment, I'm not
> entirely sure when or why I added it.
> 
> Would think it would make sense to update the kdoc_files.py script to
> check and interpret the string value the same way the perl script used
> to? It seems reasonable to me that users might set "V=0" thinking that
> it disables the verbosity. Other verbosity checks are based on the
> string containing a 1,

kernel-doc has a set of "-W" flags to control its verbosity. Direct
support for KBUILD_VERBOSE was added there just to make it bug-compatible
with kernel-doc.pl when building via Makefile.

Yet, as using it via "make htmldocs" don't use "-W", IMO it makes
sense to ensure that "-Wall" is enabled if V=1.

> (some even use 2 for even more printing).

Documentation had support for V=2, but this was dropped on this
commit:
	c0d3b83100c8 ("kbuild: do not print extra logs for V=2")

> I'm not entirely sure what the best implementation for python is to
> avoid this misinterpretation, so I haven't drafted a proper patch yet.

Perhaps something like the patch below (untested).

-- 
Thanks,
Mauro

[PATCH] doc tools: better handle KBUILD_VERBOSE

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>

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..40984ea78f12 100644
--- a/tools/lib/python/kdoc/kdoc_files.py
+++ b/tools/lib/python/kdoc/kdoc_files.py
@@ -238,7 +238,22 @@ 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
+
+            #
+            # kernel-doc logic was likelly called via Sphinx.
+            # Enable all warnings.
+            #
+            if verbose:
+                werror=True
+                wreturn=True
+                wshort_desc=True
+                wcontents_before_sections=True
 
         if out_style is None:
             out_style = OutputFormat()