From e970637707f4f8e5bd098b09090b755f2f57898b Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Fri, 2 Jan 2026 12:06:57 -0800 Subject: docs: find-unused-docs.sh: fixup directory usage The recent move of this script from scripts/ to tools/docs/ did not account for the 'cd' directory usage. Update "cd .." to "cd ../.." to make the script self-correcting. This also eliminates a shell warning: ./tools/docs/find-unused-docs.sh: line 33: cd: Documentation/: No such file or directory Fixes: 184414c6a6ca ("docs: move find-unused-docs.sh to tools/docs") Signed-off-by: Randy Dunlap Fixes: 184414c6a6ca (docs: move find-unused-docs.sh to tools/docs) Signed-off-by: Matthew Wilcox (Oracle) Reviewed-by: Matthew Wilcox (Oracle) Signed-off-by: Jonathan Corbet Message-ID: <20260102200657.1040234-1-rdunlap@infradead.org> --- tools/docs/find-unused-docs.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'tools/docs') diff --git a/tools/docs/find-unused-docs.sh b/tools/docs/find-unused-docs.sh index 05552dbda5bc..ca4e607ec3f7 100755 --- a/tools/docs/find-unused-docs.sh +++ b/tools/docs/find-unused-docs.sh @@ -28,7 +28,7 @@ if ! [ -d "$1" ]; then fi cd "$( dirname "${BASH_SOURCE[0]}" )" -cd .. +cd ../.. cd Documentation/ -- cgit v1.2.3 From eba6ffd126cd52358181ed5a179644a161f9c65f Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Mon, 19 Jan 2026 13:05:01 +0100 Subject: docs: kdoc: move kernel-doc to tools/docs kernel-doc is the last documentation-related tool still living outside of the tools/docs directory; the time has come to move it over. [mchehab: fixed kdoc lib location] Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Message-ID: <311d17e403524349940a8b12de6b5e91e554b1f4.1768823489.git.mchehab+huawei@kernel.org> --- Documentation/conf.py | 2 +- Documentation/doc-guide/kernel-doc.rst | 8 +- Documentation/kbuild/kbuild.rst | 2 +- Documentation/process/coding-style.rst | 2 +- .../translations/it_IT/doc-guide/kernel-doc.rst | 8 +- .../translations/sp_SP/process/coding-style.rst | 2 +- .../translations/zh_CN/doc-guide/kernel-doc.rst | 10 +- Documentation/translations/zh_CN/kbuild/kbuild.rst | 2 +- .../translations/zh_CN/process/coding-style.rst | 2 +- .../translations/zh_TW/process/coding-style.rst | 2 +- MAINTAINERS | 2 - Makefile | 2 +- drivers/gpu/drm/i915/Makefile | 2 +- scripts/kernel-doc | 1 - scripts/kernel-doc.py | 360 --------------------- tools/docs/find-unused-docs.sh | 2 +- tools/docs/kernel-doc | 360 +++++++++++++++++++++ tools/docs/sphinx-build-wrapper | 2 +- 18 files changed, 384 insertions(+), 387 deletions(-) delete mode 120000 scripts/kernel-doc delete mode 100755 scripts/kernel-doc.py create mode 100755 tools/docs/kernel-doc (limited to 'tools/docs') diff --git a/Documentation/conf.py b/Documentation/conf.py index 16d025af1f30..652be9221246 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -585,7 +585,7 @@ pdf_documents = [ # kernel-doc extension configuration for running Sphinx directly (e.g. by Read # the Docs). In a normal build, these are supplied from the Makefile via command # line arguments. -kerneldoc_bin = "../scripts/kernel-doc.py" +kerneldoc_bin = "../tools/docs/kernel-doc" # Not used now kerneldoc_srctree = ".." def setup(app): diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst index b56128d7f5c3..8d2c09fb36e4 100644 --- a/Documentation/doc-guide/kernel-doc.rst +++ b/Documentation/doc-guide/kernel-doc.rst @@ -54,7 +54,7 @@ Running the ``kernel-doc`` tool with increased verbosity and without actual output generation may be used to verify proper formatting of the documentation comments. For example:: - scripts/kernel-doc -v -none drivers/foo/bar.c + tools/docs/kernel-doc -v -none drivers/foo/bar.c The documentation format of ``.c`` files is also verified by the kernel build when it is requested to perform extra gcc checks:: @@ -365,7 +365,7 @@ differentiated by whether the macro name is immediately followed by a left parenthesis ('(') for function-like macros or not followed by one for object-like macros. -Function-like macros are handled like functions by ``scripts/kernel-doc``. +Function-like macros are handled like functions by ``tools/docs/kernel-doc``. They may have a parameter list. Object-like macros have do not have a parameter list. @@ -596,8 +596,8 @@ from the source file. The kernel-doc extension is included in the kernel source tree, at ``Documentation/sphinx/kerneldoc.py``. Internally, it uses the -``scripts/kernel-doc`` script to extract the documentation comments from the -source. +``tools/docs/kernel-doc`` script to extract the documentation comments from +the source. .. _kernel_doc: diff --git a/Documentation/kbuild/kbuild.rst b/Documentation/kbuild/kbuild.rst index 82826b0332df..5a9013bacfb7 100644 --- a/Documentation/kbuild/kbuild.rst +++ b/Documentation/kbuild/kbuild.rst @@ -180,7 +180,7 @@ architecture. KDOCFLAGS --------- Specify extra (warning/error) flags for kernel-doc checks during the build, -see scripts/kernel-doc for which flags are supported. Note that this doesn't +see tools/docs/kernel-doc for which flags are supported. Note that this doesn't (currently) apply to documentation builds. ARCH diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst index 258158637f65..35b381230f6e 100644 --- a/Documentation/process/coding-style.rst +++ b/Documentation/process/coding-style.rst @@ -614,7 +614,7 @@ it. When commenting the kernel API functions, please use the kernel-doc format. See the files at :ref:`Documentation/doc-guide/ ` and -``scripts/kernel-doc`` for details. Note that the danger of over-commenting +``tools/docs/kernel-doc`` for details. Note that the danger of over-commenting applies to kernel-doc comments all the same. Do not add boilerplate kernel-doc which simply reiterates what's obvious from the signature of the function. diff --git a/Documentation/translations/it_IT/doc-guide/kernel-doc.rst b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst index aa0e31d353d6..bac959b8b7b9 100644 --- a/Documentation/translations/it_IT/doc-guide/kernel-doc.rst +++ b/Documentation/translations/it_IT/doc-guide/kernel-doc.rst @@ -80,7 +80,7 @@ Al fine di verificare che i commenti siano formattati correttamente, potete eseguire il programma ``kernel-doc`` con un livello di verbosità alto e senza che questo produca alcuna documentazione. Per esempio:: - scripts/kernel-doc -v -none drivers/foo/bar.c + tools/docs/kernel-doc -v -none drivers/foo/bar.c Il formato della documentazione è verificato della procedura di generazione del kernel quando viene richiesto di effettuare dei controlli extra con GCC:: @@ -378,7 +378,7 @@ distinguono in base al fatto che il nome della macro simile a funzione sia immediatamente seguito da una parentesi sinistra ('(') mentre in quelle simili a oggetti no. -Le macro simili a funzioni sono gestite come funzioni da ``scripts/kernel-doc``. +Le macro simili a funzioni sono gestite come funzioni da ``tools/docs/kernel-doc``. Possono avere un elenco di parametri. Le macro simili a oggetti non hanno un elenco di parametri. @@ -595,7 +595,7 @@ documentazione presenti nel file sorgente (*source*). L'estensione kernel-doc fa parte dei sorgenti del kernel, la si può trovare in ``Documentation/sphinx/kerneldoc.py``. Internamente, viene utilizzato -lo script ``scripts/kernel-doc`` per estrarre i commenti di documentazione +lo script ``tools/docs/kernel-doc`` per estrarre i commenti di documentazione dai file sorgenti. Come utilizzare kernel-doc per generare pagine man @@ -604,4 +604,4 @@ Come utilizzare kernel-doc per generare pagine man Se volete utilizzare kernel-doc solo per generare delle pagine man, potete farlo direttamente dai sorgenti del kernel:: - $ scripts/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^tools) | scripts/split-man.pl /tmp/man + $ tools/docs/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^tools) | scripts/split-man.pl /tmp/man diff --git a/Documentation/translations/sp_SP/process/coding-style.rst b/Documentation/translations/sp_SP/process/coding-style.rst index 025223be9706..7d63aa8426e6 100644 --- a/Documentation/translations/sp_SP/process/coding-style.rst +++ b/Documentation/translations/sp_SP/process/coding-style.rst @@ -633,7 +633,7 @@ posiblemente POR QUÉ hace esto. Al comentar las funciones de la API del kernel, utilice el formato kernel-doc. Consulte los archivos en :ref:`Documentation/doc-guide/ ` -y ``scripts/kernel-doc`` para más detalles. +y ``tools/docs/kernel-doc`` para más detalles. El estilo preferido para comentarios largos (de varias líneas) es: diff --git a/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst b/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst index ccfb9b8329c2..fb2bbaaa85c1 100644 --- a/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst +++ b/Documentation/translations/zh_CN/doc-guide/kernel-doc.rst @@ -43,7 +43,7 @@ kernel-doc注释用 ``/**`` 作为开始标记。 ``kernel-doc`` 工具将提取 用详细模式和不生成实际输出来运行 ``kernel-doc`` 工具，可以验证文档注释的格式 是否正确。例如:: - scripts/kernel-doc -v -none drivers/foo/bar.c + tools/docs/kernel-doc -v -none drivers/foo/bar.c 当请求执行额外的gcc检查时，内核构建将验证文档格式:: @@ -473,7 +473,7 @@ doc: *title* 如果没有选项，kernel-doc指令将包含源文件中的所有文档注释。 kernel-doc扩展包含在内核源代码树中，位于 ``Documentation/sphinx/kerneldoc.py`` 。 -在内部，它使用 ``scripts/kernel-doc`` 脚本从源代码中提取文档注释。 +在内部，它使用 ``tools/docs/kernel-doc`` 脚本从源代码中提取文档注释。 .. _kernel_doc_zh: @@ -482,18 +482,18 @@ kernel-doc扩展包含在内核源代码树中，位于 ``Documentation/sphinx/k 如果您只想使用kernel-doc生成手册页，可以从内核git树这样做:: - $ scripts/kernel-doc -man \ + $ tools/docs/kernel-doc -man \ $(git grep -l '/\*\*' -- :^Documentation :^tools) \ | scripts/split-man.pl /tmp/man 一些旧版本的git不支持路径排除语法的某些变体。 以下命令之一可能适用于这些版本:: - $ scripts/kernel-doc -man \ + $ tools/docs/kernel-doc -man \ $(git grep -l '/\*\*' -- . ':!Documentation' ':!tools') \ | scripts/split-man.pl /tmp/man - $ scripts/kernel-doc -man \ + $ tools/docs/kernel-doc -man \ $(git grep -l '/\*\*' -- . ":(exclude)Documentation" ":(exclude)tools") \ | scripts/split-man.pl /tmp/man diff --git a/Documentation/translations/zh_CN/kbuild/kbuild.rst b/Documentation/translations/zh_CN/kbuild/kbuild.rst index 57f5cf5b2cdd..a477b4b08958 100644 --- a/Documentation/translations/zh_CN/kbuild/kbuild.rst +++ b/Documentation/translations/zh_CN/kbuild/kbuild.rst @@ -174,7 +174,7 @@ UTS_MACHINE 变量（在某些架构中还包括内核配置）来猜测正确 KDOCFLAGS --------- 指定在构建过程中用于 kernel-doc 检查的额外（警告/错误）标志，查看 -scripts/kernel-doc 了解支持的标志。请注意，这目前不适用于文档构建。 +tools/docs/kernel-doc 了解支持的标志。请注意，这目前不适用于文档构建。 ARCH ---- diff --git a/Documentation/translations/zh_CN/process/coding-style.rst b/Documentation/translations/zh_CN/process/coding-style.rst index 0484d0c65c25..5a342a024c01 100644 --- a/Documentation/translations/zh_CN/process/coding-style.rst +++ b/Documentation/translations/zh_CN/process/coding-style.rst @@ -545,7 +545,7 @@ Linux 里这是提倡的做法，因为这样可以很简单的给读者提供 也可以加上它做这些事情的原因。 当注释内核 API 函数时，请使用 kernel-doc 格式。详见 -Documentation/translations/zh_CN/doc-guide/index.rst 和 scripts/kernel-doc 。 +Documentation/translations/zh_CN/doc-guide/index.rst 和 tools/docs/kernel-doc 。 长 (多行) 注释的首选风格是： diff --git a/Documentation/translations/zh_TW/process/coding-style.rst b/Documentation/translations/zh_TW/process/coding-style.rst index 311c6f6bad0b..e2ba97b3d8bb 100644 --- a/Documentation/translations/zh_TW/process/coding-style.rst +++ b/Documentation/translations/zh_TW/process/coding-style.rst @@ -548,7 +548,7 @@ Linux 裏這是提倡的做法，因爲這樣可以很簡單的給讀者提供 也可以加上它做這些事情的原因。 當註釋內核 API 函數時，請使用 kernel-doc 格式。詳見 -Documentation/translations/zh_CN/doc-guide/index.rst 和 scripts/kernel-doc 。 +Documentation/translations/zh_CN/doc-guide/index.rst 和 tools/docs/kernel-doc 。 長 (多行) 註釋的首選風格是： diff --git a/MAINTAINERS b/MAINTAINERS index 02ec226dd571..d009e2da2215 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -7523,7 +7523,6 @@ S: Maintained P: Documentation/doc-guide/maintainer-profile.rst T: git git://git.lwn.net/linux.git docs-next F: Documentation/ -F: scripts/kernel-doc* F: tools/lib/python/* F: tools/docs/ F: tools/net/ynl/pyynl/lib/doc_generator.py @@ -7561,7 +7560,6 @@ M: Mauro Carvalho Chehab L: linux-doc@vger.kernel.org S: Maintained F: Documentation/sphinx/ -F: scripts/kernel-doc* F: tools/lib/python/* F: tools/docs/ diff --git a/Makefile b/Makefile index 3cd00b62cde9..81a4ab11256c 100644 --- a/Makefile +++ b/Makefile @@ -460,7 +460,7 @@ HOSTPKG_CONFIG = pkg-config # the KERNELDOC macro needs to be exported, as scripts/Makefile.build # has a logic to call it -KERNELDOC = $(srctree)/scripts/kernel-doc.py +KERNELDOC = $(srctree)/tools/docs/kernel-doc export KERNELDOC KBUILD_USERHOSTCFLAGS := -Wall -Wmissing-prototypes -Wstrict-prototypes \ diff --git a/drivers/gpu/drm/i915/Makefile b/drivers/gpu/drm/i915/Makefile index 4db24050edb0..c979c579de66 100644 --- a/drivers/gpu/drm/i915/Makefile +++ b/drivers/gpu/drm/i915/Makefile @@ -443,7 +443,7 @@ always-$(CONFIG_DRM_I915_WERROR) += \ quiet_cmd_hdrtest = HDRTEST $(patsubst %.hdrtest,%.h,$@) cmd_hdrtest = $(CC) $(filter-out $(CFLAGS_GCOV), $(c_flags)) -S -o /dev/null -x c /dev/null -include $<; \ - $(srctree)/scripts/kernel-doc -none -Werror $<; touch $@ + $(KERNELDOC) -none -Werror $<; touch $@ $(obj)/%.hdrtest: $(src)/%.h FORCE $(call if_changed_dep,hdrtest) diff --git a/scripts/kernel-doc b/scripts/kernel-doc deleted file mode 120000 index 3b6ef807791a..000000000000 --- a/scripts/kernel-doc +++ /dev/null @@ -1 +0,0 @@ -kernel-doc.py \ No newline at end of file diff --git a/scripts/kernel-doc.py b/scripts/kernel-doc.py deleted file mode 100755 index 4e3b9cfe3fd7..000000000000 --- a/scripts/kernel-doc.py +++ /dev/null @@ -1,360 +0,0 @@ -#!/usr/bin/env python3 -# SPDX-License-Identifier: GPL-2.0 -# Copyright(c) 2025: Mauro Carvalho Chehab . -# -# pylint: disable=C0103,R0912,R0914,R0915 -# -# NOTE: While kernel-doc requires at least version 3.6 to run, the -# command line should work with Python 3.2+ (tested with 3.4). -# The rationale is that it shall fail gracefully during Kernel -# compilation with older Kernel versions. Due to that: -# - encoding line is needed here; -# - f-strings cannot be used in this file. -# - libraries that require newer versions can only be included -# after the Python version has been checked. -# -# Converted from the kernel-doc script originally written in Perl -# under GPLv2, copyrighted since 1998 by the following authors: -# -# Aditya Srivastava -# Akira Yokosawa -# Alexander A. Klimov -# Alexander Lobakin -# André Almeida -# Andy Shevchenko -# Anna-Maria Behnsen -# Armin Kuster -# Bart Van Assche -# Ben Hutchings -# Borislav Petkov -# Chen-Yu Tsai -# Coco Li -# Conchúr Navid -# Daniel Santos -# Danilo Cesar Lemes de Paula -# Dan Luedtke -# Donald Hunter -# Gabriel Krisman Bertazi -# Greg Kroah-Hartman -# Harvey Harrison -# Horia Geanta -# Ilya Dryomov -# Jakub Kicinski -# Jani Nikula -# Jason Baron -# Jason Gunthorpe -# Jérémy Bobbio -# Johannes Berg -# Johannes Weiner -# Jonathan Cameron -# Jonathan Corbet -# Jonathan Neuschäfer -# Kamil Rytarowski -# Kees Cook -# Laurent Pinchart -# Levin, Alexander (Sasha Levin) -# Linus Torvalds -# Lucas De Marchi -# Mark Rutland -# Markus Heiser -# Martin Waitz -# Masahiro Yamada -# Matthew Wilcox -# Mauro Carvalho Chehab -# Michal Wajdeczko -# Michael Zucchi -# Mike Rapoport -# Niklas Söderlund -# Nishanth Menon -# Paolo Bonzini -# Pavan Kumar Linga -# Pavel Pisa -# Peter Maydell -# Pierre-Louis Bossart -# Randy Dunlap -# Richard Kennedy -# Rich Walker -# Rolf Eike Beer -# Sakari Ailus -# Silvio Fricke -# Simon Huggins -# Tim Waugh -# Tomasz Warniełło -# Utkarsh Tripathi -# valdis.kletnieks@vt.edu -# Vegard Nossum -# Will Deacon -# Yacine Belkadi -# Yujie Liu - -""" -Print formatted kernel documentation to stdout. - -Read C language source or header FILEs, extract embedded -documentation comments, and print formatted documentation -to standard output. - -The documentation comments are identified by the ``/**`` -opening comment mark. - -See Documentation/doc-guide/kernel-doc.rst for the -documentation comment syntax. -""" - -import argparse -import logging -import os -import sys - -# Import Python modules - -LIB_DIR = "../tools/lib/python" -SRC_DIR = os.path.dirname(os.path.realpath(__file__)) - -sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR)) - -WERROR_RETURN_CODE = 3 - -DESC = """ -Read C language source or header FILEs, extract embedded documentation comments, -and print formatted documentation to standard output. - -The documentation comments are identified by the "/**" opening comment mark. - -See Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax. -""" - -EXPORT_FILE_DESC = """ -Specify an additional FILE in which to look for EXPORT_SYMBOL information. - -May be used multiple times. -""" - -EXPORT_DESC = """ -Only output documentation for symbols that have been -exported using EXPORT_SYMBOL() and related macros in any input -FILE or -export-file FILE. -""" - -INTERNAL_DESC = """ -Only output documentation for symbols that have NOT been -exported using EXPORT_SYMBOL() and related macros in any input -FILE or -export-file FILE. -""" - -FUNCTION_DESC = """ -Only output documentation for the given function or DOC: section -title. All other functions and DOC: sections are ignored. - -May be used multiple times. -""" - -NOSYMBOL_DESC = """ -Exclude the specified symbol from the output documentation. - -May be used multiple times. -""" - -FILES_DESC = """ -Header and C source files to be parsed. -""" - -WARN_CONTENTS_BEFORE_SECTIONS_DESC = """ -Warn if there are contents before sections (deprecated). - -This option is kept just for backward-compatibility, but it does nothing, -neither here nor at the original Perl script. -""" - - -class MsgFormatter(logging.Formatter): - """Helper class to format warnings in a similar way to kernel-doc.pl.""" - - def format(self, record): - record.levelname = record.levelname.capitalize() - return logging.Formatter.format(self, record) - -def main(): - """ - Main program. - - By default, the return value is: - - - 0: success or Python version is not compatible with - kernel-doc. If -Werror is not used, it will also - return 0 if there are issues at kernel-doc markups; - - - 1: an abnormal condition happened; - - - 2: argparse issued an error; - - - 3: -Werror is used, and one or more unfiltered parse warnings happened. - """ - - parser = argparse.ArgumentParser(formatter_class=argparse.RawTextHelpFormatter, - description=DESC) - - # - # Normal arguments - # - parser.add_argument("-v", "-verbose", "--verbose", action="store_true", - help="Verbose output, more warnings and other information.") - - parser.add_argument("-d", "-debug", "--debug", action="store_true", - help="Enable debug messages") - - parser.add_argument("-M", "-modulename", "--modulename", - default="Kernel API", - help="Allow setting a module name at the output.") - - parser.add_argument("-l", "-enable-lineno", "--enable_lineno", - action="store_true", - help="Enable line number output (only in ReST mode)") - - # - # Arguments to control the warning behavior - # - parser.add_argument("-Wreturn", "--wreturn", action="store_true", - help="Warns about the lack of a return markup on functions.") - - parser.add_argument("-Wshort-desc", "-Wshort-description", "--wshort-desc", - action="store_true", - help="Warns if initial short description is missing") - - parser.add_argument("-Wcontents-before-sections", - "--wcontents-before-sections", action="store_true", - help=WARN_CONTENTS_BEFORE_SECTIONS_DESC) - - parser.add_argument("-Wall", "--wall", action="store_true", - help="Enable all types of warnings") - - parser.add_argument("-Werror", "--werror", action="store_true", - help="Treat warnings as errors.") - - parser.add_argument("-export-file", "--export-file", action='append', - help=EXPORT_FILE_DESC) - - # - # Output format mutually-exclusive group - # - out_group = parser.add_argument_group("Output format selection (mutually exclusive)") - - out_fmt = out_group.add_mutually_exclusive_group() - - out_fmt.add_argument("-m", "-man", "--man", action="store_true", - help="Output troff manual page format.") - out_fmt.add_argument("-r", "-rst", "--rst", action="store_true", - help="Output reStructuredText format (default).") - out_fmt.add_argument("-N", "-none", "--none", action="store_true", - help="Do not output documentation, only warnings.") - - # - # Output selection mutually-exclusive group - # - sel_group = parser.add_argument_group("Output selection (mutually exclusive)") - sel_mut = sel_group.add_mutually_exclusive_group() - - sel_mut.add_argument("-e", "-export", "--export", action='store_true', - help=EXPORT_DESC) - - sel_mut.add_argument("-i", "-internal", "--internal", action='store_true', - help=INTERNAL_DESC) - - sel_mut.add_argument("-s", "-function", "--symbol", action='append', - help=FUNCTION_DESC) - - # - # Those are valid for all 3 types of filter - # - parser.add_argument("-n", "-nosymbol", "--nosymbol", action='append', - help=NOSYMBOL_DESC) - - parser.add_argument("-D", "-no-doc-sections", "--no-doc-sections", - action='store_true', help="Don't output DOC sections") - - parser.add_argument("files", metavar="FILE", - nargs="+", help=FILES_DESC) - - args = parser.parse_args() - - if args.wall: - args.wreturn = True - args.wshort_desc = True - args.wcontents_before_sections = True - - logger = logging.getLogger() - - if not args.debug: - logger.setLevel(logging.INFO) - else: - logger.setLevel(logging.DEBUG) - - formatter = MsgFormatter('%(levelname)s: %(message)s') - - handler = logging.StreamHandler() - handler.setFormatter(formatter) - - logger.addHandler(handler) - - python_ver = sys.version_info[:2] - if python_ver < (3,6): - # - # Depending on the Kernel configuration, kernel-doc --none is called at - # build time. As we don't want to break compilation due to the - # usage of an old Python version, return 0 here. - # - if args.none: - logger.error("Python 3.6 or later is required by kernel-doc. Skipping checks") - sys.exit(0) - - sys.exit("Python 3.6 or later is required by kernel-doc. Aborting.") - - if python_ver < (3,7): - logger.warning("Python 3.7 or later is required for correct results") - - # - # Import kernel-doc libraries only after checking the Python version - # - from kdoc.kdoc_files import KernelFiles # pylint: disable=C0415 - from kdoc.kdoc_output import RestFormat, ManFormat # pylint: disable=C0415 - - if args.man: - out_style = ManFormat(modulename=args.modulename) - elif args.none: - out_style = None - else: - out_style = RestFormat() - - kfiles = KernelFiles(verbose=args.verbose, - out_style=out_style, werror=args.werror, - wreturn=args.wreturn, wshort_desc=args.wshort_desc, - wcontents_before_sections=args.wcontents_before_sections) - - kfiles.parse(args.files, export_file=args.export_file) - - for t in kfiles.msg(enable_lineno=args.enable_lineno, export=args.export, - internal=args.internal, symbol=args.symbol, - nosymbol=args.nosymbol, export_file=args.export_file, - no_doc_sections=args.no_doc_sections): - msg = t[1] - if msg: - print(msg) - - error_count = kfiles.errors - if not error_count: - sys.exit(0) - - if args.werror: - print("%s warnings as errors" % error_count) # pylint: disable=C0209 - sys.exit(WERROR_RETURN_CODE) - - if args.verbose: - print("%s errors" % error_count) # pylint: disable=C0209 - - sys.exit(0) - -# -# Call main method -# -if __name__ == "__main__": - main() diff --git a/tools/docs/find-unused-docs.sh b/tools/docs/find-unused-docs.sh index ca4e607ec3f7..53514c759dc1 100755 --- a/tools/docs/find-unused-docs.sh +++ b/tools/docs/find-unused-docs.sh @@ -54,7 +54,7 @@ for file in `find $1 -name '*.c'`; do if [[ ${FILES_INCLUDED[$file]+_} ]]; then continue; fi - str=$(PYTHONDONTWRITEBYTECODE=1 scripts/kernel-doc -export "$file" 2>/dev/null) + str=$(PYTHONDONTWRITEBYTECODE=1 tools/docs/kernel-doc -export "$file" 2>/dev/null) if [[ -n "$str" ]]; then echo "$file" fi diff --git a/tools/docs/kernel-doc b/tools/docs/kernel-doc new file mode 100755 index 000000000000..a19a92566780 --- /dev/null +++ b/tools/docs/kernel-doc @@ -0,0 +1,360 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: GPL-2.0 +# Copyright(c) 2025: Mauro Carvalho Chehab . +# +# pylint: disable=C0103,R0912,R0914,R0915 +# +# NOTE: While kernel-doc requires at least version 3.6 to run, the +# command line should work with Python 3.2+ (tested with 3.4). +# The rationale is that it shall fail gracefully during Kernel +# compilation with older Kernel versions. Due to that: +# - encoding line is needed here; +# - f-strings cannot be used in this file. +# - libraries that require newer versions can only be included +# after the Python version has been checked. +# +# Converted from the kernel-doc script originally written in Perl +# under GPLv2, copyrighted since 1998 by the following authors: +# +# Aditya Srivastava +# Akira Yokosawa +# Alexander A. Klimov +# Alexander Lobakin +# André Almeida +# Andy Shevchenko +# Anna-Maria Behnsen +# Armin Kuster +# Bart Van Assche +# Ben Hutchings +# Borislav Petkov +# Chen-Yu Tsai +# Coco Li +# Conchúr Navid +# Daniel Santos +# Danilo Cesar Lemes de Paula +# Dan Luedtke +# Donald Hunter +# Gabriel Krisman Bertazi +# Greg Kroah-Hartman +# Harvey Harrison +# Horia Geanta +# Ilya Dryomov +# Jakub Kicinski +# Jani Nikula +# Jason Baron +# Jason Gunthorpe +# Jérémy Bobbio +# Johannes Berg +# Johannes Weiner +# Jonathan Cameron +# Jonathan Corbet +# Jonathan Neuschäfer +# Kamil Rytarowski +# Kees Cook +# Laurent Pinchart +# Levin, Alexander (Sasha Levin) +# Linus Torvalds +# Lucas De Marchi +# Mark Rutland +# Markus Heiser +# Martin Waitz +# Masahiro Yamada +# Matthew Wilcox +# Mauro Carvalho Chehab +# Michal Wajdeczko +# Michael Zucchi +# Mike Rapoport +# Niklas Söderlund +# Nishanth Menon +# Paolo Bonzini +# Pavan Kumar Linga +# Pavel Pisa +# Peter Maydell +# Pierre-Louis Bossart +# Randy Dunlap +# Richard Kennedy +# Rich Walker +# Rolf Eike Beer +# Sakari Ailus +# Silvio Fricke +# Simon Huggins +# Tim Waugh +# Tomasz Warniełło +# Utkarsh Tripathi +# valdis.kletnieks@vt.edu +# Vegard Nossum +# Will Deacon +# Yacine Belkadi +# Yujie Liu + +""" +Print formatted kernel documentation to stdout. + +Read C language source or header FILEs, extract embedded +documentation comments, and print formatted documentation +to standard output. + +The documentation comments are identified by the ``/**`` +opening comment mark. + +See Documentation/doc-guide/kernel-doc.rst for the +documentation comment syntax. +""" + +import argparse +import logging +import os +import sys + +# Import Python modules + +LIB_DIR = "../lib/python" +SRC_DIR = os.path.dirname(os.path.realpath(__file__)) + +sys.path.insert(0, os.path.join(SRC_DIR, LIB_DIR)) + +WERROR_RETURN_CODE = 3 + +DESC = """ +Read C language source or header FILEs, extract embedded documentation comments, +and print formatted documentation to standard output. + +The documentation comments are identified by the "/**" opening comment mark. + +See Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax. +""" + +EXPORT_FILE_DESC = """ +Specify an additional FILE in which to look for EXPORT_SYMBOL information. + +May be used multiple times. +""" + +EXPORT_DESC = """ +Only output documentation for symbols that have been +exported using EXPORT_SYMBOL() and related macros in any input +FILE or -export-file FILE. +""" + +INTERNAL_DESC = """ +Only output documentation for symbols that have NOT been +exported using EXPORT_SYMBOL() and related macros in any input +FILE or -export-file FILE. +""" + +FUNCTION_DESC = """ +Only output documentation for the given function or DOC: section +title. All other functions and DOC: sections are ignored. + +May be used multiple times. +""" + +NOSYMBOL_DESC = """ +Exclude the specified symbol from the output documentation. + +May be used multiple times. +""" + +FILES_DESC = """ +Header and C source files to be parsed. +""" + +WARN_CONTENTS_BEFORE_SECTIONS_DESC = """ +Warn if there are contents before sections (deprecated). + +This option is kept just for backward-compatibility, but it does nothing, +neither here nor at the original Perl script. +""" + + +class MsgFormatter(logging.Formatter): + """Helper class to format warnings in a similar way to kernel-doc.pl.""" + + def format(self, record): + record.levelname = record.levelname.capitalize() + return logging.Formatter.format(self, record) + +def main(): + """ + Main program. + + By default, the return value is: + + - 0: success or Python version is not compatible with + kernel-doc. If -Werror is not used, it will also + return 0 if there are issues at kernel-doc markups; + + - 1: an abnormal condition happened; + + - 2: argparse issued an error; + + - 3: -Werror is used, and one or more unfiltered parse warnings happened. + """ + + parser = argparse.ArgumentParser(formatter_class=argparse.RawTextHelpFormatter, + description=DESC) + + # + # Normal arguments + # + parser.add_argument("-v", "-verbose", "--verbose", action="store_true", + help="Verbose output, more warnings and other information.") + + parser.add_argument("-d", "-debug", "--debug", action="store_true", + help="Enable debug messages") + + parser.add_argument("-M", "-modulename", "--modulename", + default="Kernel API", + help="Allow setting a module name at the output.") + + parser.add_argument("-l", "-enable-lineno", "--enable_lineno", + action="store_true", + help="Enable line number output (only in ReST mode)") + + # + # Arguments to control the warning behavior + # + parser.add_argument("-Wreturn", "--wreturn", action="store_true", + help="Warns about the lack of a return markup on functions.") + + parser.add_argument("-Wshort-desc", "-Wshort-description", "--wshort-desc", + action="store_true", + help="Warns if initial short description is missing") + + parser.add_argument("-Wcontents-before-sections", + "--wcontents-before-sections", action="store_true", + help=WARN_CONTENTS_BEFORE_SECTIONS_DESC) + + parser.add_argument("-Wall", "--wall", action="store_true", + help="Enable all types of warnings") + + parser.add_argument("-Werror", "--werror", action="store_true", + help="Treat warnings as errors.") + + parser.add_argument("-export-file", "--export-file", action='append', + help=EXPORT_FILE_DESC) + + # + # Output format mutually-exclusive group + # + out_group = parser.add_argument_group("Output format selection (mutually exclusive)") + + out_fmt = out_group.add_mutually_exclusive_group() + + out_fmt.add_argument("-m", "-man", "--man", action="store_true", + help="Output troff manual page format.") + out_fmt.add_argument("-r", "-rst", "--rst", action="store_true", + help="Output reStructuredText format (default).") + out_fmt.add_argument("-N", "-none", "--none", action="store_true", + help="Do not output documentation, only warnings.") + + # + # Output selection mutually-exclusive group + # + sel_group = parser.add_argument_group("Output selection (mutually exclusive)") + sel_mut = sel_group.add_mutually_exclusive_group() + + sel_mut.add_argument("-e", "-export", "--export", action='store_true', + help=EXPORT_DESC) + + sel_mut.add_argument("-i", "-internal", "--internal", action='store_true', + help=INTERNAL_DESC) + + sel_mut.add_argument("-s", "-function", "--symbol", action='append', + help=FUNCTION_DESC) + + # + # Those are valid for all 3 types of filter + # + parser.add_argument("-n", "-nosymbol", "--nosymbol", action='append', + help=NOSYMBOL_DESC) + + parser.add_argument("-D", "-no-doc-sections", "--no-doc-sections", + action='store_true', help="Don't output DOC sections") + + parser.add_argument("files", metavar="FILE", + nargs="+", help=FILES_DESC) + + args = parser.parse_args() + + if args.wall: + args.wreturn = True + args.wshort_desc = True + args.wcontents_before_sections = True + + logger = logging.getLogger() + + if not args.debug: + logger.setLevel(logging.INFO) + else: + logger.setLevel(logging.DEBUG) + + formatter = MsgFormatter('%(levelname)s: %(message)s') + + handler = logging.StreamHandler() + handler.setFormatter(formatter) + + logger.addHandler(handler) + + python_ver = sys.version_info[:2] + if python_ver < (3,6): + # + # Depending on the Kernel configuration, kernel-doc --none is called at + # build time. As we don't want to break compilation due to the + # usage of an old Python version, return 0 here. + # + if args.none: + logger.error("Python 3.6 or later is required by kernel-doc. Skipping checks") + sys.exit(0) + + sys.exit("Python 3.6 or later is required by kernel-doc. Aborting.") + + if python_ver < (3,7): + logger.warning("Python 3.7 or later is required for correct results") + + # + # Import kernel-doc libraries only after checking the Python version + # + from kdoc.kdoc_files import KernelFiles # pylint: disable=C0415 + from kdoc.kdoc_output import RestFormat, ManFormat # pylint: disable=C0415 + + if args.man: + out_style = ManFormat(modulename=args.modulename) + elif args.none: + out_style = None + else: + out_style = RestFormat() + + kfiles = KernelFiles(verbose=args.verbose, + out_style=out_style, werror=args.werror, + wreturn=args.wreturn, wshort_desc=args.wshort_desc, + wcontents_before_sections=args.wcontents_before_sections) + + kfiles.parse(args.files, export_file=args.export_file) + + for t in kfiles.msg(enable_lineno=args.enable_lineno, export=args.export, + internal=args.internal, symbol=args.symbol, + nosymbol=args.nosymbol, export_file=args.export_file, + no_doc_sections=args.no_doc_sections): + msg = t[1] + if msg: + print(msg) + + error_count = kfiles.errors + if not error_count: + sys.exit(0) + + if args.werror: + print("%s warnings as errors" % error_count) # pylint: disable=C0209 + sys.exit(WERROR_RETURN_CODE) + + if args.verbose: + print("%s errors" % error_count) # pylint: disable=C0209 + + sys.exit(0) + +# +# Call main method +# +if __name__ == "__main__": + main() diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrapper index 7a5fcef25429..cb2a5005e633 100755 --- a/tools/docs/sphinx-build-wrapper +++ b/tools/docs/sphinx-build-wrapper @@ -246,7 +246,7 @@ class SphinxBuilder: # self.sphinxbuild = os.environ.get("SPHINXBUILD", "sphinx-build") self.kerneldoc = self.get_path(os.environ.get("KERNELDOC", - "scripts/kernel-doc.py")) + "tools/docs/kernel-doc")) self.builddir = self.get_path(builddir, use_cwd=True, abs_path=True) # -- cgit v1.2.3 From 32e9a42440a230b14c438099bc5fccb5012a638a Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 19 Jan 2026 13:05:02 +0100 Subject: docs: kdoc: move the return values to the helper message It makes sense to describe what kernel-doc is expected to return on its help message. Move such messages to argparse epilog. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Message-ID: <3bcfa48016770929fcd073376515e3ff0b777ea8.1768823489.git.mchehab+huawei@kernel.org> --- tools/docs/kernel-doc | 27 +++++++++++++++------------ 1 file changed, 15 insertions(+), 12 deletions(-) (limited to 'tools/docs') diff --git a/tools/docs/kernel-doc b/tools/docs/kernel-doc index a19a92566780..902397804e80 100755 --- a/tools/docs/kernel-doc +++ b/tools/docs/kernel-doc @@ -166,6 +166,20 @@ This option is kept just for backward-compatibility, but it does nothing, neither here nor at the original Perl script. """ +EPILOG = """ +The return value is: + +- 0: success or Python version is not compatible with +kernel-doc. If -Werror is not used, it will also +return 0 if there are issues at kernel-doc markups; + +- 1: an abnormal condition happened; + +- 2: argparse issued an error; + +- 3: When -Werror is used, it means that one or more unfiltered parse + warnings happened. +""" class MsgFormatter(logging.Formatter): """Helper class to format warnings in a similar way to kernel-doc.pl.""" @@ -178,21 +192,10 @@ def main(): """ Main program. - By default, the return value is: - - - 0: success or Python version is not compatible with - kernel-doc. If -Werror is not used, it will also - return 0 if there are issues at kernel-doc markups; - - - 1: an abnormal condition happened; - - - 2: argparse issued an error; - - - 3: -Werror is used, and one or more unfiltered parse warnings happened. """ parser = argparse.ArgumentParser(formatter_class=argparse.RawTextHelpFormatter, - description=DESC) + description=DESC, epilog=EPILOG) # # Normal arguments -- cgit v1.2.3 From 35c0f975ef4a96cb488bcb5fca6e852fc347bc49 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 19 Jan 2026 13:05:03 +0100 Subject: docs: kdoc: improve description of MsgFormatter The description there is quite vague. Make it clearer. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Message-ID: <94269990e2d665bec08a1b6f4d28d84939cb9d83.1768823489.git.mchehab+huawei@kernel.org> --- tools/docs/kernel-doc | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'tools/docs') diff --git a/tools/docs/kernel-doc b/tools/docs/kernel-doc index 902397804e80..aed09f9a54dd 100755 --- a/tools/docs/kernel-doc +++ b/tools/docs/kernel-doc @@ -182,7 +182,10 @@ return 0 if there are issues at kernel-doc markups; """ class MsgFormatter(logging.Formatter): - """Helper class to format warnings in a similar way to kernel-doc.pl.""" + """ + Helper class to capitalize errors and warnings, the same way + the venerable (now retired) kernel-doc.pl used to do. + """ def format(self, record): record.levelname = record.levelname.capitalize() -- cgit v1.2.3 From 4a3efd128f7da996b677151790d043ec44a00561 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Tue, 20 Jan 2026 15:50:38 -0700 Subject: docs: sphinx-build-wrapper: stop setting kerneldoc_bin for Sphinx Now that the Sphinx build does not use the kerneldoc_bin configuration variable, we shouldn't try to set it in the build wrapper or we get a nifty warning: WARNING: unknown config value 'kerneldoc_bin' in override, ignoring Signed-off-by: Jonathan Corbet --- tools/docs/sphinx-build-wrapper | 1 - 1 file changed, 1 deletion(-) (limited to 'tools/docs') diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrapper index cb2a5005e633..9f1ae1485f84 100755 --- a/tools/docs/sphinx-build-wrapper +++ b/tools/docs/sphinx-build-wrapper @@ -750,7 +750,6 @@ class SphinxBuilder: build_args = args + [ "-d", doctree_dir, - "-D", f"kerneldoc_bin={kerneldoc}", "-D", f"version={self.kernelversion}", "-D", f"release={self.kernelrelease}", "-D", f"kerneldoc_srctree={self.srctree}", -- cgit v1.2.3 From 5094f7d5ff2318edfe6f2a9632b31f0ddefd6ee4 Mon Sep 17 00:00:00 2001 From: Thomas Weißschuh Date: Sun, 18 Jan 2026 00:26:21 +0100 Subject: tools/docs: sphinx-build-wrapper: generate rust docs only once MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Currently the rust docs are generated for each entry in SPHINXDIRS. This is unnecessary as they will be the same for each one. Move the generation, so it is executed only once. Signed-off-by: Thomas Weißschuh Reviewed-by: Mauro Carvalho Chehab Tested-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Message-ID: <20260118-docs-spurious-rust-v1-1-998e14b9ed9e@weissschuh.net> --- tools/docs/sphinx-build-wrapper | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) (limited to 'tools/docs') diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrapper index 9f1ae1485f84..2f65ddc85955 100755 --- a/tools/docs/sphinx-build-wrapper +++ b/tools/docs/sphinx-build-wrapper @@ -352,23 +352,6 @@ class SphinxBuilder: except (OSError, IOError) as e: print(f"Warning: Failed to copy CSS: {e}", file=sys.stderr) - if self.rustdoc: - print("Building rust docs") - if "MAKE" in self.env: - cmd = [self.env["MAKE"]] - else: - cmd = ["make", "LLVM=1"] - - cmd += [ "rustdoc"] - if self.verbose: - print(" ".join(cmd)) - - try: - subprocess.run(cmd, check=True) - except subprocess.CalledProcessError as e: - print(f"Ignored errors when building rustdoc: {e}. Is RUST enabled?", - file=sys.stderr) - def build_pdf_file(self, latex_cmd, from_dir, path): """Builds a single pdf file using latex_cmd""" try: @@ -785,6 +768,23 @@ class SphinxBuilder: elif target == "infodocs": self.handle_info(output_dirs) + if self.rustdoc and target in ["htmldocs", "epubdocs"]: + print("Building rust docs") + if "MAKE" in self.env: + cmd = [self.env["MAKE"]] + else: + cmd = ["make", "LLVM=1"] + + cmd += [ "rustdoc"] + if self.verbose: + print(" ".join(cmd)) + + try: + subprocess.run(cmd, check=True) + except subprocess.CalledProcessError as e: + print(f"Ignored errors when building rustdoc: {e}. Is RUST enabled?", + file=sys.stderr) + def jobs_type(value): """ Handle valid values for -j. Accepts Sphinx "-jauto", plus a number -- cgit v1.2.3 From 2d652135a16b413e38e6d7fed5244690d853756b Mon Sep 17 00:00:00 2001 From: Thomas Weißschuh Date: Sun, 18 Jan 2026 00:26:22 +0100 Subject: tools/docs: sphinx-build-wrapper: make 'rustdoc' a local variable MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit All users of this variable are now in the same method. Demote the instance variable to a local one. Signed-off-by: Thomas Weißschuh Reviewed-by: Mauro Carvalho Chehab Tested-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Message-ID: <20260118-docs-spurious-rust-v1-2-998e14b9ed9e@weissschuh.net> --- tools/docs/sphinx-build-wrapper | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) (limited to 'tools/docs') diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrapper index 2f65ddc85955..76dfd5cbf178 100755 --- a/tools/docs/sphinx-build-wrapper +++ b/tools/docs/sphinx-build-wrapper @@ -123,12 +123,10 @@ class SphinxBuilder: """ Checks if Rust is enabled """ - self.rustdoc = False - config = os.path.join(self.srctree, ".config") if not os.path.isfile(config): - return + return False re_rust = re.compile(r"CONFIG_RUST=(m|y)") @@ -136,11 +134,13 @@ class SphinxBuilder: with open(config, "r", encoding="utf-8") as fp: for line in fp: if re_rust.match(line): - self.rustdoc = True - return + return True except OSError as e: print(f"Failed to open {config}", file=sys.stderr) + return False + + return False def get_sphinx_extra_opts(self, n_jobs): """ @@ -259,8 +259,6 @@ class SphinxBuilder: self.get_sphinx_extra_opts(n_jobs) - self.check_rust() - # # If venv command line argument is specified, run Sphinx from venv # @@ -680,7 +678,8 @@ class SphinxBuilder: args.extend(["-D", f"latex_elements.papersize={paper}paper"]) - if self.rustdoc: + rustdoc = self.check_rust() + if rustdoc: args.extend(["-t", "rustdoc"]) if not sphinxdirs: @@ -768,7 +767,7 @@ class SphinxBuilder: elif target == "infodocs": self.handle_info(output_dirs) - if self.rustdoc and target in ["htmldocs", "epubdocs"]: + if rustdoc and target in ["htmldocs", "epubdocs"]: print("Building rust docs") if "MAKE" in self.env: cmd = [self.env["MAKE"]] -- cgit v1.2.3 From 6f9a96cc96ea405e0f80fede761dc415e33364c7 Mon Sep 17 00:00:00 2001 From: Thomas Weißschuh Date: Sun, 18 Jan 2026 00:26:23 +0100 Subject: tools/docs: sphinx-build-wrapper: compute sphinxdirs_list earlier MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit An upcoming patch will require sphinxdirs_list to be available before the call to check_rust(). Move it up in the function. Signed-off-by: Thomas Weißschuh Reviewed-by: Mauro Carvalho Chehab Tested-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Message-ID: <20260118-docs-spurious-rust-v1-3-998e14b9ed9e@weissschuh.net> --- tools/docs/sphinx-build-wrapper | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) (limited to 'tools/docs') diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrapper index 76dfd5cbf178..04eb300dab4a 100755 --- a/tools/docs/sphinx-build-wrapper +++ b/tools/docs/sphinx-build-wrapper @@ -670,6 +670,19 @@ class SphinxBuilder: if kerneldoc.startswith(self.srctree): kerneldoc = os.path.relpath(kerneldoc, self.srctree) + if not sphinxdirs: + sphinxdirs = os.environ.get("SPHINXDIRS", ".") + + # + # sphinxdirs can be a list or a whitespace-separated string + # + sphinxdirs_list = [] + for sphinxdir in sphinxdirs: + if isinstance(sphinxdir, list): + sphinxdirs_list += sphinxdir + else: + sphinxdirs_list += sphinxdir.split() + args = [ "-b", builder, "-c", docs_dir ] if builder == "latex": @@ -682,9 +695,6 @@ class SphinxBuilder: if rustdoc: args.extend(["-t", "rustdoc"]) - if not sphinxdirs: - sphinxdirs = os.environ.get("SPHINXDIRS", ".") - # # The sphinx-build tool has a bug: internally, it tries to set # locale with locale.setlocale(locale.LC_ALL, ''). This causes a @@ -695,16 +705,6 @@ class SphinxBuilder: except locale.Error: self.env["LC_ALL"] = "C" - # - # sphinxdirs can be a list or a whitespace-separated string - # - sphinxdirs_list = [] - for sphinxdir in sphinxdirs: - if isinstance(sphinxdir, list): - sphinxdirs_list += sphinxdir - else: - sphinxdirs_list += sphinxdir.split() - # # Step 1: Build each directory in separate. # -- cgit v1.2.3 From ffb569d59c253399efb2345ddfefe7929cd7e2a8 Mon Sep 17 00:00:00 2001 From: Thomas Weißschuh Date: Sun, 18 Jan 2026 00:26:24 +0100 Subject: tools/docs: sphinx-build-wrapper: only generate rust docs when requested MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit When the user explicitly specifies SPHINXDIRS to build a specific subdirectory it is unexpected that the rust docs are also generated. Especially as their generation may dominate the execution time. Only generate the rust docs when they are part of the SPHINXDIRS requested by the user. 'rust/rustdocs' is not considered, as it is not a valid SPHINXDIRS anyways. Signed-off-by: Thomas Weißschuh Reviewed-by: Mauro Carvalho Chehab Tested-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Message-ID: <20260118-docs-spurious-rust-v1-4-998e14b9ed9e@weissschuh.net> --- tools/docs/sphinx-build-wrapper | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) (limited to 'tools/docs') diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrapper index 04eb300dab4a..78ff7ac202ef 100755 --- a/tools/docs/sphinx-build-wrapper +++ b/tools/docs/sphinx-build-wrapper @@ -119,12 +119,15 @@ class SphinxBuilder: return path - def check_rust(self): + def check_rust(self, sphinxdirs): """ Checks if Rust is enabled """ config = os.path.join(self.srctree, ".config") + if not {'.', 'rust'}.intersection(sphinxdirs): + return False + if not os.path.isfile(config): return False @@ -691,7 +694,7 @@ class SphinxBuilder: args.extend(["-D", f"latex_elements.papersize={paper}paper"]) - rustdoc = self.check_rust() + rustdoc = self.check_rust(sphinxdirs_list) if rustdoc: args.extend(["-t", "rustdoc"]) -- cgit v1.2.3 From b09cc1ddde9707ef62d2dd1070a1c99556ed7d76 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 27 Jan 2026 09:03:33 +0100 Subject: docs: sphinx-build-wrapper: allow -v override -q Documentation builds were using "-q" for a long time, but sometimes it is nice to see the Sphinx progress, without increasing build verbosity - which would also turn on kernel-doc verbosity. Instead of doing that, let's parse the sphinx-build already-existing -v: each time it is used, it increases the verbosity level. With that, if the default is to use -q, a single -v will disable quiet mode. Passing more -v will keep increasing its verbosity. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Message-ID: <38b24e97a3cbd2def418359a8e69b1b087a945ad.1769500383.git.mchehab+huawei@kernel.org> --- tools/docs/sphinx-build-wrapper | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) (limited to 'tools/docs') diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrapper index 78ff7ac202ef..8080ace60680 100755 --- a/tools/docs/sphinx-build-wrapper +++ b/tools/docs/sphinx-build-wrapper @@ -168,6 +168,7 @@ class SphinxBuilder: parser = argparse.ArgumentParser() parser.add_argument('-j', '--jobs', type=int) parser.add_argument('-q', '--quiet', action='store_true') + parser.add_argument('-v', '--verbose', default=0, action='count') # # Other sphinx-build arguments go as-is, so place them @@ -179,10 +180,14 @@ class SphinxBuilder: # Build a list of sphinx args, honoring verbosity here if specified # - verbose = self.verbose sphinx_args, self.sphinxopts = parser.parse_known_args(sphinxopts) + + verbose = sphinx_args.verbose + if self.verbose: + verbose += 1 + if sphinx_args.quiet is True: - verbose = False + verbose = 0 # # If the user explicitly sets "-j" at command line, use it. @@ -195,8 +200,11 @@ class SphinxBuilder: else: self.n_jobs = None - if not verbose: + if verbose < 1: self.sphinxopts += ["-q"] + else: + for i in range(1, sphinx_args.verbose): + self.sphinxopts += ["-v"] def __init__(self, builddir, venv=None, verbose=False, n_jobs=None, interactive=None): -- cgit v1.2.3 From 64e4882c8228b07c57e75f510b8c5d7ff46e4edc Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 27 Jan 2026 09:03:34 +0100 Subject: tools: sphinx-build-wrapper: improve its help message Besides the parameters that are passed via command line arguments, the wrapper's behavior is affected by several environment variables. Document that. While here, use __doc__ for its description. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Message-ID: --- tools/docs/sphinx-build-wrapper | 28 +++++++++++++++++++++++++--- 1 file changed, 25 insertions(+), 3 deletions(-) (limited to 'tools/docs') diff --git a/tools/docs/sphinx-build-wrapper b/tools/docs/sphinx-build-wrapper index 8080ace60680..b7c149dff06b 100755 --- a/tools/docs/sphinx-build-wrapper +++ b/tools/docs/sphinx-build-wrapper @@ -814,20 +814,42 @@ def jobs_type(value): except ValueError: raise argparse.ArgumentTypeError(f"Must be 'auto' or positive integer, got {value}") # pylint: disable=W0707 +EPILOG=""" +Besides the command line arguments, several environment variables affect its +default behavior, meant to be used when called via Kernel Makefile: + +- KERNELVERSION: Kernel major version +- KERNELRELEASE: Kernel release +- KBUILD_VERBOSE: Contains the value of "make V=[0|1] variable. + When V=0 (KBUILD_VERBOSE=0), sets verbose level to "-q". +- SPHINXBUILD: Documentation build tool (default: "sphinx-build"). +- SPHINXOPTS: Extra options pased to SPHINXBUILD + (default: "-j auto" and "-q" if KBUILD_VERBOSE=0). + The "-v" flag can be used to increase verbosity. + If V=0, the first "-v" will drop "-q". +- PYTHON3: Python command to run SPHINXBUILD +- PDFLATEX: LaTeX PDF engine. (default: "xelatex") +- LATEXOPTS: Optional set of command line arguments to the LaTeX engine +- srctree: Location of the Kernel root directory (default: "."). + +""" + def main(): """ Main function. The only mandatory argument is the target. If not specified, the other arguments will use default values if not specified at os.environ. """ - parser = argparse.ArgumentParser(description="Kernel documentation builder") + parser = argparse.ArgumentParser(formatter_class=argparse.RawTextHelpFormatter, + description=__doc__, + epilog=EPILOG) parser.add_argument("target", choices=list(TARGETS.keys()), help="Documentation target to build") parser.add_argument("--sphinxdirs", nargs="+", help="Specific directories to build") parser.add_argument("--builddir", default="output", - help="Sphinx configuration file") + help="Sphinx configuration file (default: %(default)s)") parser.add_argument("--theme", help="Sphinx theme to use") @@ -843,7 +865,7 @@ def main(): help="place build in verbose mode") parser.add_argument('-j', '--jobs', type=jobs_type, - help="Sets number of jobs to use with sphinx-build") + help="Sets number of jobs to use with sphinx-build(default: auto)") parser.add_argument('-i', '--interactive', action='store_true', help="Change latex default to run in interactive mode") -- cgit v1.2.3