* kernel-doc overly verbose with V=0
@ 2026-03-24 20:37 Jacob Keller
2026-03-25 11:50 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 4+ messages in thread
From: Jacob Keller @ 2026-03-24 20:37 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List, Shuah Khan, Randy Dunlap,
Mauro Carvalho Chehab
Cc: linux-kernel@vger.kernel.org
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.
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.
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, (some even use 2 for even more printing).
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.
Thanks,
Jake
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: kernel-doc overly verbose with V=0
2026-03-24 20:37 kernel-doc overly verbose with V=0 Jacob Keller
@ 2026-03-25 11:50 ` Mauro Carvalho Chehab
2026-03-25 20:42 ` Jacob Keller
0 siblings, 1 reply; 4+ messages in thread
From: Mauro Carvalho Chehab @ 2026-03-25 11:50 UTC (permalink / raw)
To: Jacob Keller
Cc: Jonathan Corbet, Linux Doc Mailing List, Shuah Khan, Randy Dunlap,
linux-kernel@vger.kernel.org
On Tue, 24 Mar 2026 13:37:39 -0700
Jacob Keller <jacob.e.keller@intel.com> 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@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>
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()
^ permalink raw reply related [flat|nested] 4+ messages in thread
* Re: kernel-doc overly verbose with V=0
2026-03-25 11:50 ` Mauro Carvalho Chehab
@ 2026-03-25 20:42 ` Jacob Keller
2026-03-27 6:11 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 4+ messages in thread
From: Jacob Keller @ 2026-03-25 20:42 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Jonathan Corbet, Linux Doc Mailing List, Shuah Khan, Randy Dunlap,
linux-kernel@vger.kernel.org
On 3/25/2026 4:50 AM, Mauro Carvalho Chehab wrote:
> On Tue, 24 Mar 2026 13:37:39 -0700
> Jacob Keller <jacob.e.keller@intel.com> 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.
>
Yep.
> 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
>
Strange. The Makefile does this:
ifeq ("$(origin V)", "command line")
KBUILD_VERBOSE = $(V)
endif
I can see KBUILD_VERBOSE=0 from the top level Makefile, but you're right
it doesn't seem to trigger the environment variable..
> It sounds that the problem is only if you explicitly set it without
> relying on gnu make.
>
Adding some warn prints I do see the Makefile sets KBUILD_VERBOSE=0 when
you do V=0.. and it has an export clause for KBUILD_VERBOSE
Oh, it might be your particular build doesn't have W=1 so checkdoc isn't
being defined and thus kernel-doc isn't running?
If I do "make W=1 V=0" I do actually see these lines:
> Info: ../drivers/pci/pci.c:3646 Scanning doc for function pci_acs_init
> Info: ../drivers/pci/pci.c:3663 Scanning doc for function pci_enable_atomic_ops_to_root
> Info: ../drivers/pci/pci.c:3746 Scanning doc for function pci_release_region
> Info: ../drivers/pci/pci.c:3772 Scanning doc for function __pci_request_region
> Info: ../drivers/pci/pci.c:3820 Scanning doc for function pci_request_region
> Info: ../drivers/pci/pci.c:3841 Scanning doc for function pci_release_selected_regions
> Info: ../drivers/pci/pci.c:3879 Scanning doc for function pci_request_selected_regions
> Info: ../drivers/pci/pci.c:3894 Scanning doc for function pci_request_selected_regions_exclusive
> Info: ../drivers/pci/pci.c:3910 Scanning doc for function pci_release_regions
> Info: ../drivers/pci/pci.c:3925 Scanning doc for function pci_request_regions
> Info: ../drivers/pci/pci.c:3944 Scanning doc for function pci_request_regions_exclusive
> Info: ../drivers/pci/pci.c:4026 Scanning doc for function pci_remap_iospace
> Info: ../drivers/pci/pci.c:4062 Scanning doc for function pci_unmap_iospace
> Info: ../drivers/pci/pci.c:4097 Scanning doc for function pcibios_setup
> Info: ../drivers/pci/pci.c:4109 Scanning doc for function pcibios_set_master
> Info: ../drivers/pci/pci.c:4136 Scanning doc for function pci_set_master
> Info: ../drivers/pci/pci.c:4150 Scanning doc for function pci_clear_master
> Info: ../drivers/pci/pci.c:4160 Scanning doc for function pci_set_cacheline_size
> Info: ../drivers/pci/pci.c:4198 Scanning doc for function pci_set_mwi
> Info: ../drivers/pci/pci.c:4229 Scanning doc for function pci_try_set_mwi
> Info: ../drivers/pci/pci.c:4248 Scanning doc for function pci_clear_mwi
> Info: ../drivers/pci/pci.c:4268 Scanning doc for function pci_disable_parity
> Info: ../drivers/pci/pci.c:4285 Scanning doc for function pci_intx
> Info: ../drivers/pci/pci.c:4310 Scanning doc for function pci_wait_for_pending_transaction
> Info: ../drivers/pci/pci.c:4326 Scanning doc for function pcie_flr
> Info: ../drivers/pci/pci.c:4366 Scanning doc for function pcie_reset_flr
> Info: ../drivers/pci/pci.c:4443 Scanning doc for function pci_pm_reset
> Info: ../drivers/pci/pci.c:4497 Scanning doc for function pcie_wait_for_link_status
> Info: ../drivers/pci/pci.c:4527 Scanning doc for function pcie_retrain_link
> Info: ../drivers/pci/pci.c:4592 Scanning doc for function pcie_wait_for_link_delay
> Info: ../drivers/pci/pci.c:4642 Scanning doc for function pcie_wait_for_link
> Info: ../drivers/pci/pci.c:4679 Scanning doc for function pci_bridge_wait_for_secondary_bus
> Info: ../drivers/pci/pci.c:4818 Scanning doc for function pci_bridge_secondary_bus_reset
> Info: ../drivers/pci/pci.c:5077 Scanning doc for function __pci_reset_function_locked
> Info: ../drivers/pci/pci.c:5135 Scanning doc for function pci_init_reset_methods
> Info: ../drivers/pci/pci.c:5167 Scanning doc for function pci_reset_function
> Info: ../drivers/pci/pci.c:5214 Scanning doc for function pci_reset_function_locked
> Info: ../drivers/pci/pci.c:5252 Scanning doc for function pci_try_reset_function
>> 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.
>
Right.
> Yet, as using it via "make htmldocs" don't use "-W", IMO it makes
> sense to ensure that "-Wall" is enabled if V=1.
>
We enable -Wall if KBUILD_EXTRA_WARN contains a 2:
ifeq ($(KBUILD_EXTMOD),)
ifneq ($(KBUILD_EXTRA_WARN),)
cmd_checkdoc = PYTHONDONTWRITEBYTECODE=1 $(PYTHON3) $(KERNELDOC) -none
$(KDOCFLAGS) \
$(if $(findstring 2, $(KBUILD_EXTRA_WARN)), -Wall) \
$<
endif
endif
If KBUILD_EXTRA_WARN has 2 we do -Wall, and if its any non-zero value we
enable checkdoc. KBUILD_VERBOSE is handled internally to the script so
not part of the Make invocation.
So V=0 only manifests if KBUILD_EXTRA_WARN is set.
We set KBUILD_EXTRA_WARN in top level:
ifeq ("$(origin W)", "command line")
KBUILD_EXTRA_WARN := $(W)
endif
export KBUILD_EXTRA_WARN
>> (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")
>
Looks like there's some stale leftover bits then:
#
# If KBUILD_VERBOSE contains 1, the whole command is echoed.
# If KBUILD_VERBOSE contains 2, the reason for rebuilding is printed.
#
# To put more focus on warnings, be less verbose as default
# Use 'make V=1' to see the full commands
I don't have strong opinions either way.
>> 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).
>
The patch seems reasonable, though I don't know about the enabling other
errors, as those are controlled by W=2 right now. I don't personally
have objections to enabling them with V as well, but others might?
Thanks,
Jake
^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: kernel-doc overly verbose with V=0
2026-03-25 20:42 ` Jacob Keller
@ 2026-03-27 6:11 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 4+ messages in thread
From: Mauro Carvalho Chehab @ 2026-03-27 6:11 UTC (permalink / raw)
To: Jacob Keller
Cc: Jonathan Corbet, Linux Doc Mailing List, Shuah Khan, Randy Dunlap,
linux-kernel@vger.kernel.org
On Wed, 25 Mar 2026 13:42:44 -0700
Jacob Keller <jacob.e.keller@intel.com> wrote:
> On 3/25/2026 4:50 AM, Mauro Carvalho Chehab wrote:
> > On Tue, 24 Mar 2026 13:37:39 -0700
> > Jacob Keller <jacob.e.keller@intel.com> 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.
> >
>
> Yep.
>
> > 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
> >
>
> Strange. The Makefile does this:
>
> ifeq ("$(origin V)", "command line")
> KBUILD_VERBOSE = $(V)
> endif
>
> I can see KBUILD_VERBOSE=0 from the top level Makefile, but you're right
> it doesn't seem to trigger the environment variable..
>
> > It sounds that the problem is only if you explicitly set it without
> > relying on gnu make.
> >
>
> Adding some warn prints I do see the Makefile sets KBUILD_VERBOSE=0 when
> you do V=0.. and it has an export clause for KBUILD_VERBOSE
>
> Oh, it might be your particular build doesn't have W=1 so checkdoc isn't
> being defined and thus kernel-doc isn't running?
>
> If I do "make W=1 V=0" I do actually see these lines:
>
> > Info: ../drivers/pci/pci.c:3646 Scanning doc for function pci_acs_init
> > Info: ../drivers/pci/pci.c:3663 Scanning doc for function pci_enable_atomic_ops_to_root
> > Info: ../drivers/pci/pci.c:3746 Scanning doc for function pci_release_region
> > Info: ../drivers/pci/pci.c:3772 Scanning doc for function __pci_request_region
> > Info: ../drivers/pci/pci.c:3820 Scanning doc for function pci_request_region
> > Info: ../drivers/pci/pci.c:3841 Scanning doc for function pci_release_selected_regions
> > Info: ../drivers/pci/pci.c:3879 Scanning doc for function pci_request_selected_regions
> > Info: ../drivers/pci/pci.c:3894 Scanning doc for function pci_request_selected_regions_exclusive
> > Info: ../drivers/pci/pci.c:3910 Scanning doc for function pci_release_regions
> > Info: ../drivers/pci/pci.c:3925 Scanning doc for function pci_request_regions
> > Info: ../drivers/pci/pci.c:3944 Scanning doc for function pci_request_regions_exclusive
> > Info: ../drivers/pci/pci.c:4026 Scanning doc for function pci_remap_iospace
> > Info: ../drivers/pci/pci.c:4062 Scanning doc for function pci_unmap_iospace
> > Info: ../drivers/pci/pci.c:4097 Scanning doc for function pcibios_setup
> > Info: ../drivers/pci/pci.c:4109 Scanning doc for function pcibios_set_master
> > Info: ../drivers/pci/pci.c:4136 Scanning doc for function pci_set_master
> > Info: ../drivers/pci/pci.c:4150 Scanning doc for function pci_clear_master
> > Info: ../drivers/pci/pci.c:4160 Scanning doc for function pci_set_cacheline_size
> > Info: ../drivers/pci/pci.c:4198 Scanning doc for function pci_set_mwi
> > Info: ../drivers/pci/pci.c:4229 Scanning doc for function pci_try_set_mwi
> > Info: ../drivers/pci/pci.c:4248 Scanning doc for function pci_clear_mwi
> > Info: ../drivers/pci/pci.c:4268 Scanning doc for function pci_disable_parity
> > Info: ../drivers/pci/pci.c:4285 Scanning doc for function pci_intx
> > Info: ../drivers/pci/pci.c:4310 Scanning doc for function pci_wait_for_pending_transaction
> > Info: ../drivers/pci/pci.c:4326 Scanning doc for function pcie_flr
> > Info: ../drivers/pci/pci.c:4366 Scanning doc for function pcie_reset_flr
> > Info: ../drivers/pci/pci.c:4443 Scanning doc for function pci_pm_reset
> > Info: ../drivers/pci/pci.c:4497 Scanning doc for function pcie_wait_for_link_status
> > Info: ../drivers/pci/pci.c:4527 Scanning doc for function pcie_retrain_link
> > Info: ../drivers/pci/pci.c:4592 Scanning doc for function pcie_wait_for_link_delay
> > Info: ../drivers/pci/pci.c:4642 Scanning doc for function pcie_wait_for_link
> > Info: ../drivers/pci/pci.c:4679 Scanning doc for function pci_bridge_wait_for_secondary_bus
> > Info: ../drivers/pci/pci.c:4818 Scanning doc for function pci_bridge_secondary_bus_reset
> > Info: ../drivers/pci/pci.c:5077 Scanning doc for function __pci_reset_function_locked
> > Info: ../drivers/pci/pci.c:5135 Scanning doc for function pci_init_reset_methods
> > Info: ../drivers/pci/pci.c:5167 Scanning doc for function pci_reset_function
> > Info: ../drivers/pci/pci.c:5214 Scanning doc for function pci_reset_function_locked
> > Info: ../drivers/pci/pci.c:5252 Scanning doc for function pci_try_reset_function
>
> >> 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.
> >
>
> Right.
>
> > Yet, as using it via "make htmldocs" don't use "-W", IMO it makes
> > sense to ensure that "-Wall" is enabled if V=1.
> >
>
> We enable -Wall if KBUILD_EXTRA_WARN contains a 2:
>
> ifeq ($(KBUILD_EXTMOD),)
> ifneq ($(KBUILD_EXTRA_WARN),)
> cmd_checkdoc = PYTHONDONTWRITEBYTECODE=1 $(PYTHON3) $(KERNELDOC) -none
> $(KDOCFLAGS) \
> $(if $(findstring 2, $(KBUILD_EXTRA_WARN)), -Wall) \
> $<
> endif
> endif
>
> If KBUILD_EXTRA_WARN has 2 we do -Wall, and if its any non-zero value we
> enable checkdoc. KBUILD_VERBOSE is handled internally to the script so
> not part of the Make invocation.
>
> So V=0 only manifests if KBUILD_EXTRA_WARN is set.
>
> We set KBUILD_EXTRA_WARN in top level:
>
> ifeq ("$(origin W)", "command line")
> KBUILD_EXTRA_WARN := $(W)
> endif
>
> export KBUILD_EXTRA_WARN
Good point.
>
> >> (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")
> >
>
> Looks like there's some stale leftover bits then:
>
> #
> # If KBUILD_VERBOSE contains 1, the whole command is echoed.
> # If KBUILD_VERBOSE contains 2, the reason for rebuilding is printed.
> #
> # To put more focus on warnings, be less verbose as default
> # Use 'make V=1' to see the full commands
> I don't have strong opinions either way.
>
>
> >> 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).
> >
>
> The patch seems reasonable, though I don't know about the enabling other
> errors, as those are controlled by W=2 right now. I don't personally
> have objections to enabling them with V as well, but others might?
As W=2 already turns those, I opted to just apply the fix
for KBUILD_VERBOSE without touching -W macros:
https://lore.kernel.org/linux-doc/7a99788db75630fb14828d612c0fd77c45ec1891.1774591065.git.mchehab+huawei@kernel.org/T/#u
On a very quick test with:
$ make W=2 V=0 drivers/pci/
and with:
$ KBUILD_VERBOSE="asdf" ./scripts/kernel-doc drivers/pci/ -none
$ KBUILD_VERBOSE="" ./scripts/kernel-doc drivers/pci/ -none
$ KBUILD_VERBOSE="0" ./scripts/kernel-doc drivers/pci/ -none
$ KBUILD_VERBOSE=0 ./scripts/kernel-doc drivers/pci/ -none
None of the above enabled verbosity.
Using either one of the above:
$ KBUILD_VERBOSE=1 ./scripts/kernel-doc drivers/pci/ -none
$ KBUILD_VERBOSE="1" ./scripts/kernel-doc drivers/pci/ -none
made it verbose.
So, I guess this should be enough to fix the issue. Please test
and reply to the patch if it works or not for you.
Thanks,
Mauro
^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2026-03-27 6:11 UTC | newest]
Thread overview: 4+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2026-03-24 20:37 kernel-doc overly verbose with V=0 Jacob Keller
2026-03-25 11:50 ` Mauro Carvalho Chehab
2026-03-25 20:42 ` Jacob Keller
2026-03-27 6:11 ` Mauro Carvalho Chehab
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox