* 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