summaryrefslogtreecommitdiff
path: root/tools/docs
AgeCommit message (Collapse)Author
11 daysdocs: makefile: move rustdoc check to the build wrapperMauro Carvalho Chehab
The makefile logic to detect if rust is enabled is not working the way it was expected: instead of using the current setup for CONFIG_RUST, it uses a cached version from a previous build. The root cause is that the current logic inside docs/Makefile uses a cached version of CONFIG_RUST, from the last time a non documentation target was executed. That's perfectly fine for Sphinx build, as it doesn't need to read or depend on any CONFIG_*. So, instead of relying at the cache, move the logic to the wrapper script and let it check the current content of .config, to verify if CONFIG_RUST was selected. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <c06b1834ef02099735c13ee1109fa2a2b9e47795.1763722971.git.mchehab+huawei@kernel.org>
2025-11-21get_feat.pl: remove it, as it got replaced by get_feat.pyMauro Carvalho Chehab
Now that this was rewritten in Python, we can remove the old tool. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <1f53e0fa48616af189ce98b45a65cc0c245e7aaf.1763492868.git.mchehab+huawei@kernel.org>
2025-11-21tools/docs/get_feat.py: convert get_feat.pl to PythonMauro Carvalho Chehab
As we want to call Python code directly at the Sphinx extension, convert get_feat.pl to Python. The code was made to be (almost) bug-compatible with the Perl version, with two exceptions: 1. Currently, Perl script outputs a wrong table if arch is set to a non-existing value; 2. the ReST table output when --feat is used without --arch has an invalid format, as the number of characters for the table delimiters are wrong. Those two bugs were fixed while testing the conversion. Additionally, another caveat was solved: the output when --feat is used without arch and the feature doesn't exist doesn't contain an empty table anymore. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <03c26cee1ec567804735a33047e625ef5ab7bfa8.1763492868.git.mchehab+huawei@kernel.org>
2025-11-18docs: bring some order to our Python module hierarchyJonathan Corbet
Now that we have tools/lib/python for our Python modules, turn them into proper packages with a single namespace so that everything can just use tools/lib/python in sys.path. No functional change. Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <20251110220430.726665-3-corbet@lwn.net>
2025-11-18docs: Move the python libraries to tools/lib/pythonJonathan Corbet
"scripts/lib" was always a bit of an awkward place for Python modules. We already have tools/lib; create a tools/lib/python, move the libraries there, and update the users accordingly. While at it, move the contents of tools/docs/lib. Rather than make another directory, just put these documentation-oriented modules under "kdoc". Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <20251110220430.726665-2-corbet@lwn.net>
2025-11-10tools/docs/get_abi.py: fix get_abi library directoryMauro Carvalho Chehab
changeset a5dd93016f20 ("docs: move get_abi.py to tools/docs") moved the script location, but didn't update library location, causing it to fail. Fixes: a5dd93016f20 ("docs: move get_abi.py to tools/docs") Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <3839bc4db2d5c7e14dd2686876a2c7b5d72a46cd.1762523688.git.mchehab+huawei@kernel.org>
2025-11-03Merge branch 'tools-final2' into docs-mwJonathan Corbet
Our documentation-related tools are spread out over various directories; several are buried in the scripts/ dumping ground. That makes them harder to discover and harder to maintain. Recent work has started accumulating our documentation-related tools in /tools/docs. This series nearly completes that task, moving most of the rest of our various utilities there, hopefully fixing up all of the relevant references in the process. The one exception is scripts/kernel-doc; that move turned up some other problems, so I have dropped it until those are ironed out. At the end, rather than move the old, Perl kernel-doc, I simply removed it.
2025-10-29tools/docs/sphinx-build-wrapper: Emit $SPHINXOPTS later in args listAkira Yokosawa
The option list to sphinx-build via SPHINXOPTS should have higher priority than those the wrapper comes up with. sphinx-build will choose the latest one if there are duplicates. To restore the behavior of Makefile era, when the documentation builds at https://www.kernel.org/doc/html/next/ had been depending on it, reorder the flag list. Reported-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org> Closes: https://lore.kernel.org/20251007-awesome-guan-of-greatness-e6ec75@lemur/ Reported-by: Akira Yokosawa <akiyks@gmail.com> Closes: https://lore.kernel.org/c35e690f-0579-49cb-850c-07af98e5253a@gmail.com/ Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <eaf4bfd8-fb80-45d0-b3ec-4047692ebbed@gmail.com>
2025-10-28docs: move find-unused-docs.sh to tools/docsJonathan Corbet
...and update references accordingly. Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Acked-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2025-10-28docs: move test_doc_build.py to tools/docsJonathan Corbet
Add this tool to tools/docs. Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Acked-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2025-10-28docs: move get_abi.py to tools/docsJonathan Corbet
Move this tool out of scripts/ to join the other documentation tools; fix up a couple of erroneous references in the process. It's worth noting that this script will fail badly unless one has a PYTHONPATH referencing scripts/lib/abi. Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Acked-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2025-10-28docs: move scripts/documentation-file-ref-check to tools/docsJonathan Corbet
Add this script to the growing collection of documentation tools. Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Acked-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2025-10-28docs: move checktransupdate.py to tools/docsJonathan Corbet
The checktranslate.py tool currently languishes in scripts/; move it to tools/docs and update references accordingly. Cc: Alex Shi <alexs@kernel.org> Cc: Yanteng Si <si.yanteng@linux.dev> Cc: Dongliang Mu <dzm91@hust.edu.cn> Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Acked-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2025-10-28docs: Move the "features" tools to tools/docsJonathan Corbet
The scripts for managing the features docs are found in three different directories; unite them all under tools/docs and update references as needed. Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Acked-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2025-10-17Merge branch 'build-script' into docs-mwJonathan Corbet
Quoth Mauro: This series should probably be called: "Move the trick-or-treat build hacks accumulated over time into a single place and document them." as this reflects its main goal. As such: - it places the jobserver logic on a library; - it removes sphinx/parallel-wrapper.sh; - the code now properly implements a jobserver-aware logic to do the parallelism when called via GNU make, failing back to "-j" when there's no jobserver; - converts check-variable-fonts.sh to Python and uses it via function call; - drops an extra script to generate man pages, adding a makefile target for it; - ensures that return code is 0 when PDF successfully builds; - about half of the script is comments and documentation. I tried to do my best to document all tricks that are inside the script. This way, the docs build steps is now documented. It should be noticed that it is out of the scope of this series to change the implementation. Surely the process can be improved, but first let's consolidate and document everything on a single place. Such script was written in a way that it can be called either directly or via a Makefile. Running outside Makefile is interesting specially when debug is needed. The command line interface replaces the need of having lots of env vars before calling sphinx-build: $ ./tools/docs/sphinx-build-wrapper --help usage: sphinx-build-wrapper [-h] [--sphinxdirs SPHINXDIRS [SPHINXDIRS ...]] [--conf CONF] [--builddir BUILDDIR] [--theme THEME] [--css CSS] [--paper {,a4,letter}] [-v] [-j JOBS] [-i] [-V [VENV]] {cleandocs,linkcheckdocs,htmldocs,epubdocs,texinfodocs,infodocs,mandocs,latexdocs,pdfdocs,xmldocs} Kernel documentation builder positional arguments: {cleandocs,linkcheckdocs,htmldocs,epubdocs,texinfodocs,infodocs,mandocs,latexdocs,pdfdocs,xmldocs} Documentation target to build options: -h, --help show this help message and exit --sphinxdirs SPHINXDIRS [SPHINXDIRS ...] Specific directories to build --conf CONF Sphinx configuration file --builddir BUILDDIR Sphinx configuration file --theme THEME Sphinx theme to use --css CSS Custom CSS file for HTML/EPUB --paper {,a4,letter} Paper size for LaTeX/PDF output -v, --verbose place build in verbose mode -j, --jobs JOBS Sets number of jobs to use with sphinx-build -i, --interactive Change latex default to run in interactive mode -V, --venv [VENV] If used, run Sphinx from a venv dir (default dir: sphinx_latest) the only mandatory argument is the target, which is identical with "make" targets. The call inside Makefile doesn't use the last four arguments. They're there to help identifying problems at the build: -v makes the output verbose; -j helps to test parallelism; -i runs latexmk in interactive mode, allowing to debug PDF build issues; -V is useful when testing it with different venvs. When used with GNU make (or some other make which implements jobserver), a call like: make -j <targets> htmldocs will make the wrapper to automatically use POSIX jobserver to claim the number of available job slots, calling sphinx-build with a "-j" parameter reflecting it. ON such case, the default can be overriden via SPHINXDIRS argument. Visiable changes when compared with the old behavior: When V=0, the only visible difference is that: - pdfdocs target now returns 0 on success, 1 on failures. This addresses an issue over the current process where we it always return success even on failures; - it will now print the name of PDF files that failed to build, if any. In verbose mode, sphinx-build-wrapper and sphinx-build command lines are now displayed.
2025-10-17tools: docs: parse_data_structs.py: accept more reftypesMauro Carvalho Chehab
Current regex is limited to only some c-domain reftypes. There are several others. Change the code to pick the name specified there. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <5c146923d1e3183893f290216fb1378954e2e540.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17tools: docs: parse_data_structs.py: add namespace supportMauro Carvalho Chehab
C domain supports a ".. c:namespace::" tag that allows setting a symbol namespace. This is used within the kernel to avoid warnings about duplicated symbols. This is specially important for syscalls, as each subsystem may have their own documentation for them. This is specially true for ioctl. When such tag is used, all C domain symbols have c++ style, e.g. they'll become "{namespace}.{reference}". Allow specifying C namespace at the exception files, avoiding the need of override rules for every symbol. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <cc27ec60ceb3bdac4197fb7266d2df8155edacda.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17tools: docs: parse_data_structs.py: get rid of process_exceptions()Mauro Carvalho Chehab
Add an extra parameter to parse_file to make it handle exceptions internally, cleaning up the API. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <8575bbc94ff706aa7e7cc3a188399ca17a3169e6.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17tools: docs: parse_data_structs: make process_exceptions two stagesMauro Carvalho Chehab
Split the logic which parses exceptions on two stages, preparing the exceptions file to have rules that will affect xref generation. For now, preserve the original API. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <da9ca5f2ce1ffcfb355e32e676ff013607c227e0.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17docs: kernel_include.py: fix line numbers for TOCMauro Carvalho Chehab
On TOC output, we need to embeed line numbers with ViewList. Change the parse class to produce a line-number parsed result, and adjust the output accordingly. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <74eed96e32f79eaaef7a99ffe7c3224fed369c27.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17tools: docs: parse_data_structs.py: output a line numberMauro Carvalho Chehab
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <dcffa6844dede00052f5fb851a857991468f22b5.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17tools: docs: parse_data_structs.py: drop contents headerMauro Carvalho Chehab
When used in practice, one may want to have multiple header files on a single rst file, like: *********************** Digital TV uAPI symbols *********************** .. contents:: Table of Contents :depth: 2 :local: Frontend ======== .. kernel-include:: include/uapi/linux/dvb/frontend.h :generate-cross-refs: :toc: Demux ===== .. kernel-include:: include/uapi/linux/dvb/dmx.h :generate-cross-refs: :toc: ... So, don't add ..contents:: here. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <4bf353e5248133a3b0abd82519a38453402fe7c6.1759329363.git.mchehab+huawei@kernel.org>
2025-10-08tools/docs: sphinx-build-wrapper: -q is a boolean, not an integerMauro Carvalho Chehab
As reported by Konstantin, sphinx-build -q is a boolean, not an integer. Fix the code. Reported-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org> Closes: https://lore.kernel.org/all/871pnepxfy.fsf@trenco.lwn.net/ Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Reviewed-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <cafa10cddce3e5342a66c73f3f51a17fb6c7f5d3.1759851791.git.mchehab+huawei@kernel.org>
2025-10-01tools/docs: sphinx-build-wrapper: pdflatex is needed only for pdfMauro Carvalho Chehab
Fix the logic which checks for pdflatex. Currently, it complains for both pdfdocs and latexdocs, but for the latter, all it is needed is Sphinx. Reported-by: Akira Yokosawa <akiyks@gmail.com> Closes: https://lore.kernel.org/linux-doc/cover.1758881658.git.mchehab+huawei@kernel.org/T/#ma81ff2e11b8579e5edc23e4381e464081ae668b7 Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <313df7b4aab653e8fc40c30120c0dbebf8a0bcb1.1759328070.git.mchehab+huawei@kernel.org>
2025-09-25tools/docs/sphinx-build-wrapper: allow skipping sphinx-build stepMauro Carvalho Chehab
Most targets have two steps: - step 1: run sphinx-build; - step 2: run a post-build logic. The second step can be as simple as copying static files like CSS, but may may also envolve running make. allowing to skip the first step helps debugging what's broken, and also allows using make command line arguments like --ignore-errors. Add an option to skip step 1. Requested-by: Akira Yokosawa <akiyks@gmail.com> Link: https://lore.kernel.org/linux-doc/5031e0c4-f17e-41b8-8955-959989e797f2@gmail.com/ Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <30dae295606ae1735f3bbeef4ca041a76dcd4540.1758539031.git.mchehab+huawei@kernel.org>
2025-09-25tools/docs: sphinx-build-wrapper: fix compat with recent TumbleweedMauro Carvalho Chehab
On recent versions of openSUSE Tumbleweed, sphinx-buildis is no longer a Python script, but something else. Such change is due to how it now handles alternatives: https://en.opensuse.org/openSUSE:Migrating_to_libalternatives_with_alts The most common approach that distros use for alternatives is via symlinks: lrwxrwxrwx 1 root root 22 out 31 2024 /usr/bin/java -> /etc/alternatives/java lrwxrwxrwx 1 root root 37 mar 5 2025 /etc/alternatives/java -> /usr/lib/jvm/java-21-openjdk/bin/java With such approach, one can sun the script with either: <sphinx> python3 <script> However, openSUSE's implementation uses an ELF binary (/usr/bin/alts), which breaks the latter format. It is needed to allow users to specify the Python version to be used while building docs, as some distros like Leap 15.x are shipped with: - older, unsupported python3/python3-sphinx packages; - more modern python3xx/python3xx-sphinx packages that work properly. On such distros, building docs require running make with: make PYTHON3=python3.11 htmldocs Heh, even on more moderen distros where python3-sphinx is supported, one may still want to use a newer package, for instance, due to performance issues, as: - with Python < 3.11, kernel-doc is 3 times slower; - while building htmldocs with Python 3.13/Sphinx 8.x takes about 3 minutes on a modern machine, using Sphinx < 8.0 can take up to 16 minutes to build docs (7.x are the worse ones and require lots of RAM). So, even with not too old distros, one still may want to use for instance PYTHON3=python3.11. To acommodate using PYTHON3 without breaking on Tumbleweed, add a workaround that will only use: $(PYTHON3) sphinx-build if PYTHON3 env var is not default. While here, drop the special check for venv, as, with venv, we can just call sphinx-build directly without any extra checks. Reported-by: Randy Dunlap <rdunlap@infradead.org> Link: https://lore.kernel.org/all/883df949-0281-4a39-8745-bcdcce3a5594@infradead.org/ Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Tested-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <8917f862e0b8484c68408c274129c9f37a7aefb4.1758539031.git.mchehab+huawei@kernel.org>
2025-09-21docs: conf.py: get rid of load_config.pyMauro Carvalho Chehab
The code here was meant to handle 3 functions: 1. allow having a separate conf.py file, per subdir; 2. generate a list of latex documents. 3. set "subproject" tag if SPHINXDIRS points to a subdir. We don't have (1) anymore, and (3) is now properly handled entirely inside conf.py. So, only (3) is still needed, and this is a single-line change at conf.py. So, drop it, moving the remaining code to conf.py. While here, drop a duplicated $(RUSTDOC) command-line argument. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <ec998f9f268a401ca6aa36e3221d39c97efeccaa.1758361087.git.mchehab+huawei@kernel.org>
2025-09-21tools/docs: sphinx-build-wrapper: handle sphinx-build errorsMauro Carvalho Chehab
If sphinx-build returns an error, exit the script. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <b7e152291fadd91694cbb6b086caefa4b6470fdd.1758361087.git.mchehab+huawei@kernel.org>
2025-09-18tools/docs: sphinx-build-wrapper: add support to run inside venvMauro Carvalho Chehab
Sometimes, it is desired to run Sphinx from a virtual environment. Add a command line parameter to automatically build Sphinx from such environment. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Message-ID: <e34fa63a61e75a0ec86b37c9b5fafa6677f44c6c.1758196090.git.mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2025-09-18tools/docs: sphinx-* break documentation bulds on openSUSEMauro Carvalho Chehab
Before this patch, building htmldocs on opensuseLEAP works fine: # make htmldocs Available Python versions: /usr/bin/python3.11 Python 3.6.15 not supported. Changing to /usr/bin/python3.11 Python 3.6.15 not supported. Changing to /usr/bin/python3.11 Using alabaster theme Using Python kernel-doc ... As the logic detects that Python 3.6 is too old and recommends intalling python311-Sphinx. If installed, documentation builds work like a charm. Yet, some develpers complained that running python3.11 instead of python3 should not happen. So, let's break the build to make them happier: $ make htmldocs Python 3.6.15 not supported. Bailing out You could run, instead: /usr/bin/python3.11 tools/docs/sphinx-build-wrapper htmldocs \ --sphinxdirs=. --conf=conf.py --builddir=Documentation/output --theme= --css= \ --paper= Python 3.6.15 not supported. Bailing out make[2]: *** [Documentation/Makefile:76: htmldocs] Error 1 make[1]: *** [Makefile:1806: htmldocs] Error 2 make: *** [Makefile:248: __sub-make] Error 2 It should be noticed that: 1. after this change, sphinx-pre-install needs to be called by hand: $ /usr/bin/python3.11 tools/docs/sphinx-pre-install Detected OS: openSUSE Leap 15.6. Sphinx version: 7.2.6 All optional dependencies are met. Needed package dependencies are met. 2. sphinx-build-wrapper will auto-detect python3.11 and suggest a way to build the docs using the parameters passed via make variables. In this specific example: /usr/bin/python3.11 tools/docs/sphinx-build-wrapper htmldocs --sphinxdirs=. --conf=conf.py --theme= --css= --paper= 3. As this needs to be executed outside docs Makefile, it won't run the validation check scripts nor build Rust documentation if enabled, as the extra scripts are part of the docs Makefile. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Message-ID: <0635c311295300e9fb48c0ea607e2408910036e3.1758196090.git.mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2025-09-18tools/docs: sphinx-build-wrapper: move rust doc builder to wrapperMauro Carvalho Chehab
Simplify even further the docs Makefile by moving rust build logic to the wrapper. After this change, running make on an environment with rust enabled works as expected. With CONFIG_RUST: $ make O=/tmp/foo LLVM=1 SPHINXDIRS=peci htmldocs make[1]: Entrando no diretório '/tmp/foo' Using alabaster theme Using Python kernel-doc GEN Makefile DESCEND objtool CC arch/x86/kernel/asm-offsets.s INSTALL libsubcmd_headers CALL /new_devel/docs/scripts/checksyscalls.sh RUSTC L rust/core.o BINDGEN rust/bindings/bindings_generated.rs BINDGEN rust/bindings/bindings_helpers_generated.rs ... Without it: $ make SPHINXDIRS=peci htmldocs Using alabaster theme Using Python kernel-doc Both work as it is it is supposed to do. After the change, it is also possible to build directly with the script by passing "--rustodoc". if CONFIG_RUST, this works fine: $ ./tools/docs/sphinx-build-wrapper --sphinxdirs peci --rustdoc -- htmldocs Using alabaster theme Using Python kernel-doc SYNC include/config/auto.conf ... RUSTC L rust/core.o ... If not, it will produce a warning that RUST may be disabled: $ ./tools/docs/sphinx-build-wrapper --sphinxdirs peci --rustdoc -- htmldocs Using alabaster theme Using Python kernel-doc *** *** Configuration file ".config" not found! *** *** Please run some configurator (e.g. "make oldconfig" or *** "make menuconfig" or "make xconfig"). *** make[1]: *** [/new_devel/docs/Makefile:829: .config] Error 1 make: *** [Makefile:248: __sub-make] Error 2 Ignored errors when building rustdoc: Command '['make', 'LLVM=1', 'rustdoc']' returned non-zero exit status 2.. Is RUST enabled? Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Message-ID: <fa1235ccf859f6ebfeef7ffba0ebde2015a75042.1758196090.git.mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2025-09-18docs: add support to build manpages from kerneldoc outputMauro Carvalho Chehab
Generating man files currently requires running a separate script. The target also doesn't appear at the docs Makefile. Add support for mandocs at the Makefile, adding the build logic inside sphinx-build-wrapper, updating documentation and dropping the ancillary script. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Message-ID: <3d248d724e7f3154f6e3a227e5923d7360201de9.1758196090.git.mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2025-09-18tools/docs: sphinx-build-wrapper: Fix output for duplicated namesMauro Carvalho Chehab
When SPHINXDIRS is used, basename may be identical for different files. If this happens, the summary and error detection won't be accurate. Fix it by using relative names from builddir. While here, don't duplicate names. Report, instead: - SUCCESS output PDF file was built - FAILED latexmk/xelatex didn't build any PDF output - FAILED: no .tex files were generated Sphinx didn't build any tex file for SPHINXDIRS directories - FAILED ({python exception}) When a concurrent.futures is catched. Usually indicates an internal error at the build logic. With that, building multiple dirs with the same name is reported properly: $ make V=1 SPHINXDIRS="admin-guide/media driver-api/media userspace-api/media" pdfdocs Summary ======= admin-guide/media/pdf/media.pdf : SUCCESS driver-api/media/pdf/media.pdf : SUCCESS userspace-api/media/pdf/media.pdf: SUCCESS And if at least one of them fails, return code will be 1. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Message-ID: <d4a4f16f6c0c423ad38531a490888be3bf01e574.1758196090.git.mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2025-09-18tools/docs,scripts: sphinx-*: prevent sphinx-build crashesMauro Carvalho Chehab
On a properly set system, LANG and LC_ALL is always defined. However, some distros like Debian, Gentoo and their variants start with those undefioned. When Sphinx tries to set a locale with: locale.setlocale(locale.LC_ALL, '') It raises an exception, making Sphinx fail. This is more likely to happen with test containers. Add a logic to detect and workaround such issue by setting locale to C. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Message-ID: <1d0afad8fe3d83182be3a08eb00dd71322e23e69.1758196090.git.mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2025-09-18tools/docs: sphinx-build-wrapper: allow building PDF files in parallelMauro Carvalho Chehab
Use POSIX jobserver when available or -j<number> to run PDF builds in parallel, restoring pdf build performance. Yet, running it when debugging troubles is a bad idea, so, when calling directly via command line, except if "-j" is splicitly requested, it will serialize the build. With such change, a PDF doc builds now takes around 5 minutes on a Ryzen 9 machine with 32 cpu threads: # Explicitly paralelize both Sphinx and LaTeX pdf builds $ make cleandocs; time scripts/sphinx-build-wrapper pdfdocs -j 33 real 5m17.901s user 15m1.499s sys 2m31.482s # Use POSIX jobserver to paralelize both sphinx-build and LaTeX $ make cleandocs; time make pdfdocs real 5m22.369s user 15m9.076s sys 2m31.419s # Serializes PDF build, while keeping Sphinx parallelized. # it is equivalent of passing -jauto via command line $ make cleandocs; time scripts/sphinx-build-wrapper pdfdocs real 11m20.901s user 13m2.910s sys 1m44.553s Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Message-ID: <42eef319f9af6f9feb12bcd74ca6392c8119929d.1758196090.git.mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2025-09-18tools/docs: sphinx-build-wrapper: add an argument for LaTeX interactive modeMauro Carvalho Chehab
By default, we use LaTeX batch mode to build docs. This way, when an error happens, the build fails. This is good for normal builds, but when debugging problems with pdf generation, the best is to use interactive mode. We already support it via LATEXOPTS, but having a command line argument makes it easier: Interactive mode: ./scripts/sphinx-build-wrapper pdfdocs --sphinxdirs peci -v -i ... Running 'xelatex --no-pdf -no-pdf -recorder ".../Documentation/output/peci/latex/peci.tex"' ... Default batch mode: ./scripts/sphinx-build-wrapper pdfdocs --sphinxdirs peci -v ... Running 'xelatex --no-pdf -no-pdf -interaction=batchmode -no-shell-escape -recorder ".../Documentation/output/peci/latex/peci.tex"' ... Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Message-ID: <9e5b9a8becc981b47ca3bf3ddce034f273400738.1758196090.git.mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2025-09-18tools/docs: sphinx-build-wrapper: add a wrapper for sphinx-buildMauro Carvalho Chehab
There are too much magic inside docs Makefile to properly run sphinx-build. Create an ancillary script that contains all kernel-related sphinx-build call logic currently at Makefile. Such script is designed to work both as an standalone command and as part of a Makefile. As such, it properly handles POSIX jobserver used by GNU make. On a side note, there was a line number increase due to the conversion (ignoring comments) is: Documentation/Makefile | 131 +++---------- tools/docs/sphinx-build-wrapper | 293 +++++++++++++++++++++++++++++++ 2 files changed, 323 insertions(+), 101 deletions(-) Comments and descriptions adds: tools/docs/sphinx-build-wrapper | 261 +++++++++++++++++++++++++++++++- So, about half of the script are comments/descriptions. This is because some things are more verbosed on Python and because it requires reading env vars from Makefile. Besides it, this script has some extra features that don't exist at the Makefile: - It can be called directly from command line; - It properly return PDF build errors. When running the script alone, it will only take handle sphinx-build targets. On other words, it won't runn make rustdoc after building htmlfiles, nor it will run the extra check scripts. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Message-ID: <80ae57b01fcfb1d338d93b8f8e26e57b69b5f16b.1758196090.git.mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2025-09-18tools/docs: python_version: move version check from sphinx-pre-installMauro Carvalho Chehab
The sphinx-pre-install code has some logic to deal with Python version, which ensures that a minimal version will be enforced for documentation build logic. Move it to a separate library to allow re-using its code. No functional changes. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Message-ID: <d134ace64b55c827565ce68f0527e20c735f0d2e.1758196090.git.mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2025-09-18tools/docs: sphinx-pre-install: allow check for alternatives and bail outMauro Carvalho Chehab
The caller script may not want an automatic execution of the new version. Add two parameters to allow showing alternatives and to bail out if version is incompatible. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Message-ID: <19777bc710bf901ffbb0ad0f1bb57b18fc01b163.1758196090.git.mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2025-09-18tools/docs: sphinx-pre-install: drop a debug printMauro Carvalho Chehab
The version print at the lib was added for debugging purposes. Get rid of it. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Message-ID: <27f76a4df2b80c38d277d58a92c85c614544e013.1758196090.git.mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2025-09-18scripts: sphinx-pre-install: move it to tools/docsMauro Carvalho Chehab
As we're reorganizing the place where doc scripts are located, move this one to tools/docs. No functional changes. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Message-ID: <5e2c40d3aebfd67b7ac7817f548bd1fa4ff661a8.1758196090.git.mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2025-09-18check-variable-fonts.py: add a helper to display instructionsMauro Carvalho Chehab
Use lib docstring to output the comments via --help/-h. With that, update the default instructions to recomment it instead of asking the user to read the source code. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Message-ID: <577162cf4e07de74c4a783f16e3404f0040e5e0a.1758196090.git.mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2025-09-18tools/docs: check-variable-fonts.py: split into a lib and an exec fileMauro Carvalho Chehab
As we'll be using the actual code inside sphinx-build-wrapper, split the library from the executable, placing the exec at the new place we've been using: tools/docs No functional changes. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Message-ID: <8adbc22df1d43b1c5a673799d2333cc429ffe9fc.1758196090.git.mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2025-09-09docs: add tools/docs/gen-redirects.pyVegard Nossum
Add a new script and a new documentation 'make' target, htmldocs-redirects. This will generate HTML stub files in the HTML documentation output directory that redirect the browser to the new path. Suggested-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org> Suggested-by: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <20250905144608.577449-4-vegard.nossum@oracle.com>
2025-09-09docs: add tools/docs/gen-renames.pyVegard Nossum
Add a new script that wraps git to trawl the repository history for renames of .rst files in the Documentation/ directory. Example usage: tools/docs/gen-renames.py --rev v6.17-rc3 > Documentation/.renames.txt The output format is simply: <old path> SPACE <new path> NEWLINE where neither <old path> nor <new path> contain the Documentation/ prefix or the .rst suffix. The file is sorted alphabetically. We can suggest rerunning the script for future renames (and squash the resulting change) or rerun it periodically to keep the file up to date. Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <20250905144608.577449-2-vegard.nossum@oracle.com>
2025-08-29tools: docs: parse_data_structs.py: add methods to return outputMauro Carvalho Chehab
When running it from command line, we want to write an output file, but when used as a class, one may just want the output content returned as a string. Split write_output() on two methods to allow both usecases. Also add an extra method to produce a TOC. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/c98bdec3380aad54178baf2751a2f1fcd128576b.1755872208.git.mchehab+huawei@kernel.org
2025-08-29tools: docs: parse-headers.py: move it from sphinx dirMauro Carvalho Chehab
As suggested by Jon, we should start having a tools/docs directory, instead of placing everything under scripts. In the specific case of parse-headers.py, the previous location is where we're placing Sphinx extensions, which is not the right place for execs. Move it to tools/docs/parse-headers.py. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/0f5ac2d704cffe9834e589b39549d2393e1237ef.1755872208.git.mchehab+huawei@kernel.org
generated by cgit v1.2.3 (git 2.46.0) at 2025-12-10 21:28:40 +0000