summaryrefslogtreecommitdiff
AgeCommit message (Collapse)Author
2025-10-01kernel-doc: output source file name at SEE ALSOMauro Carvalho Chehab
for man pages, it is helpful to know from where the man page were generated. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <ac25496a27a0c90494a634d342207ef1ff6216e9.1759327966.git.mchehab+huawei@kernel.org>
2025-10-01docs: Makefile: use PYTHONPYCACHEPREFIXMauro Carvalho Chehab
Previous cleanup patches ended dropping it when sphinx-build-wrapper were added. Also, sphinx-pre-install can also generate caches. So, re-add it for both. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <8c37576342994ea0e3466eec2602a8d989d9a5f0.1759328070.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-10-01docs: Makefile: avoid a warning when using without texliveMauro Carvalho Chehab
As reported by Randy, running make htmldocs on a machine without textlive now produce warnings: $ make O=DOCS htmldocs ../Documentation/Makefile:70: warning: overriding recipe for target 'pdfdocs' ../Documentation/Makefile:61: warning: ignoring old recipe for target 'pdfdocs' That's because the code has now two definitions for pdfdocs in case $PDFLATEX command is not found. With the new script, such special case is not needed anymore, as the script checks it. Drop the special case. Even after dropping it, on a machine without LaTeX, it will still produce an error as expected, as running: $ ./tools/docs/sphinx-build-wrapper pdfdocs Error: pdflatex or latexmk required for PDF generation does the check. After applying the patch we have: $ make SPHINXDIRS=peci htmldocs Using alabaster theme Using Python kernel-doc $ make SPHINXDIRS=peci pdfdocs Error: pdflatex or latexmk required for PDF generation make[2]: *** [Documentation/Makefile:64: pdfdocs] Error 1 make[1]: *** [/root/Makefile:1808: pdfdocs] Error 2 make: *** [Makefile:248: __sub-make] Error 2 Which is the expected behavior. Reported-by: Randy Dunlap <rdunlap@infradead.org> Link: https://lore.kernel.org/linux-doc/e7c29532-71de-496b-a89f-743cef28736e@infradead.org/ Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Acked-by: Randy Dunlap <rdunlap@infradead.org> Tested-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <cd16a7436a510116ef87cd4abbb1f3cfe358012f.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-25docs: Makefile: fix rustdoc detectionMauro Carvalho Chehab
During cleanups, the logic checking if .config exists were dropped, but removing it causes false-positives. So, re-add it. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <f414ff9b21eeb770ca1f57eb1496cc064c9bab15.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-21scripts: remove sphinx-build-wrapper from scripts/Mauro Carvalho Chehab
Commit 8a298579cdfc ("scripts: sphinx-build-wrapper: get rid of uapi/media Makefile") accidentally added scripts/sphinx-build-wrapper, probably due to some rebase issues. The file was added on a separate patch series, at tools/docs, and has other patches on the top of it, so drop this extra version. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <d26137d908dc7813fafcded2c728ec837e4df073.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-18scripts: kdoc_parser.py: warn about Python version only onceMauro Carvalho Chehab
When running kernel-doc over multiple documents, it emits one error message per file with is not what we want: $ python3.6 scripts/kernel-doc.py . --none ... Warning: ./include/trace/events/swiotlb.h:0 Python 3.7 or later is required for correct results Warning: ./include/trace/events/iommu.h:0 Python 3.7 or later is required for correct results Warning: ./include/trace/events/sock.h:0 Python 3.7 or later is required for correct results ... Change the logic to warn it only once at the library: $ python3.6 scripts/kernel-doc.py . --none Warning: Python 3.7 or later is required for correct results Warning: ./include/cxl/features.h:0 Python 3.7 or later is required for correct results When running from command line, it warns twice, but that sounds ok. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Message-ID: <68e54cf8b1201d1f683aad9bc710a99421910356.1758196090.git.mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2025-09-18tools: kernel-doc: add a see also section at man pagesMauro Carvalho Chehab
While cross-references are complex, as related ones can be on different files, we can at least correlate the ones that belong to the same file, adding a SEE ALSO section for them. The result is not bad. See for instance: $ tools/docs/sphinx-build-wrapper --sphinxdirs driver-api/media -- mandocs $ man Documentation/output/driver-api/man/edac_pci_add_device.9 edac_pci_add_device(9) Kernel Hacker's Manual edac_pci_add_device(9) NAME edac_pci_add_device - Insert the 'edac_dev' structure into the edac_pci global list and create sysfs entries associated with edac_pci structure. SYNOPSIS int edac_pci_add_device (struct edac_pci_ctl_info *pci , int edac_idx ); ARGUMENTS pci pointer to the edac_device structure to be added to the list edac_idx A unique numeric identifier to be assigned to the RETURN 0 on Success, or an error code on failure SEE ALSO edac_pci_alloc_ctl_info(9), edac_pci_free_ctl_info(9), edac_pci_alloc_index(9), edac_pci_del_device(9), edac_pci_cre‐ ate_generic_ctl(9), edac_pci_release_generic_ctl(9), edac_pci_create_sysfs(9), edac_pci_remove_sysfs(9) August 2025 edac_pci_add_device edac_pci_add_device(9) Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Message-ID: <fba25efb41eadad17a54e6275a6191173d702f00.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-18docs: Makefile: document FONTS_CONF_DENY_VF= parameterMauro Carvalho Chehab
This parameter is there for some time, but it doesn't have anything documenting it at make help. Add some documentation, pointing to the place where one can find more details. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Message-ID: <a84680c8f6f34e57c51829242ebc98a609af94c1.1758196090.git.mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2025-09-18docs: Makefile: document latex/PDF PAPER= parameterMauro Carvalho Chehab
While the build system supports this for a long time, this was never documented. Add a documentation for it. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Message-ID: <9c7b34db18642081d22c36a4203f341c1100341e.1758196090.git.mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2025-09-18docs: parallel-wrapper.sh: remove scriptMauro Carvalho Chehab
The only usage of this script was docs Makefile. Now that it is using the new sphinx-build-wrapper, which has inside the code from parallel-wrapper.sh, we can drop this script. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Message-ID: <c8ce0c78d0761370e4c9091a9423d9df9a357187.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-18scripts: check-variable-fonts.sh: convert to PythonMauro Carvalho Chehab
This script handle errors when trying to build translations with make pdfdocs. As part of our cleanup work to remove hacks from docs Makefile, convert this to python, preparing it to be part of a library to be called by sphinx-build-wrapper. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Message-ID: <d438fb01d2c00e2c2b4ac16f999d9a8ce848251b.1758196090.git.mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2025-09-18scripts/jobserver-exec: add a help messageMauro Carvalho Chehab
Currently, calling it without an argument shows an ugly error message. Instead, print a message using pythondoc as description. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Message-ID: <64b0339eac54ac0f2b3de3667a7f4f5becb1c6ae.1758196090.git.mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2025-09-18scripts/jobserver-exec: move its class to the lib directoryMauro Carvalho Chehab
To make it easier to be re-used, move the JobserverExec class to the library directory. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Message-ID: <6be7b161b6c005a9807162ebfd239af6a4e6fa47.1758196090.git.mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2025-09-18scripts/jobserver-exec: move the code to a classMauro Carvalho Chehab
Convert the code inside jobserver-exec to a class and properly document it. Using a class allows reusing the jobserver logic on other scripts. While the main code remains unchanged, being compatible with Python 2.6 and 3.0+, its coding style now follows a more modern standard, having tabs replaced by a 4-spaces indent, passing autopep8, black and pylint. The code allows using a pythonic way to enter/exit a python code, e.g. it now supports: with JobserverExec() as jobserver: jobserver.run(sys.argv[1:]) With the new code, the __exit__() function should ensure that the jobserver slot will be closed at the end, even if something bad happens somewhere. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Message-ID: <4749921b75d4e0bd85a25d4d94aa2c940fad084e.1758196090.git.mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2025-09-18docs: driver-api: fix spelling of "buses".Marneni PoornaChandu
Replace incorrect plural form "busses" with "buses" in multiple documentation files under "Documentation/driver-api". Signed-off-by: Marneni PoornaChandu <Poornachandumarneni@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <20250917220430.5815-1-Poornachandumarneni@gmail.com>
2025-09-18Documentation: fbcon: Use admonition directivesBagas Sanjaya
Use reST syntax for admonitions (notes and custom admonition for gotcha). Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com> Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Tested-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <20250909063744.30053-4-bagasdotme@gmail.com>
2025-09-18Documentation: fbcon: Reindent 8th step of attach/detach/unloadBagas Sanjaya
Properly indent 8th step text (as enumerated list item) to be inline with other steps. Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com> Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Tested-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <20250909063744.30053-3-bagasdotme@gmail.com>
2025-09-18Documentation: fbcon: Add boot options and attach/detach/unload section headingsBagas Sanjaya
These last two enumerated sections headings are in normal paragraphs, making both sections merged into "Loading" section instead. Add the headings. Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com> Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Tested-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <20250909063744.30053-2-bagasdotme@gmail.com>
2025-09-18docs: filesystems: sysfs: add remaining top level sysfs directory descriptionsAlex Tran
Finish top level sysfs directory descriptions for block, class, firmware, hypervisor, kernel, and power. Did not write one for net directory. See commit bc3a88431672 ("docs: filesystems: sysfs: remove top level sysfs net directory") Signed-off-by: Alex Tran <alex.t.tran@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <20250902023039.1351270-1-alex.t.tran@gmail.com>
2025-09-18docs: filesystems: sysfs: clarify symlink destinations in dev and ↵Alex Tran
bus/devices descriptions Change sysfs bus/devices and dev directory descriptions to provide more verbose information about the specific symlink destination the devices point to. Signed-off-by: Alex Tran <alex.t.tran@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <20250902023039.1351270-2-alex.t.tran@gmail.com>
2025-09-18docs: filesystems: sysfs: remove top level sysfs net directoryAlex Tran
The net/ directory is not present as a top level sysfs directory in standard Linux systems. Network interfaces can be accessible via /sys/class/net instead. Signed-off-by: Alex Tran <alex.t.tran@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <20250902023039.1351270-3-alex.t.tran@gmail.com>
2025-09-18docs: maintainer: Fix ambiguous subheading formattingThorsten Blum
Add a newline after both subheadings to avoid any ambiguous formatting, especially in htmldocs. Without the newline, subheadings are rendered as part of the following paragraphs, which can be confusing to read. Suggested-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Thorsten Blum <thorsten.blum@linux.dev> Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com> Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Tested-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <20250916222944.2547948-2-thorsten.blum@linux.dev>
2025-09-18docs: kdoc: a few more dump_typedef() tweaksJonathan Corbet
Merge "typedef" into the typedef_type pattern rather than repeating it later, and add some comments. Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2025-09-18docs: kdoc: remove redundant comment stripping in dump_typedef()Jonathan Corbet
By the time we get here, comments have long since been stripped out; there is no need to do it again. Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2025-09-18docs: kdoc: remove some dead code in dump_typedef()Jonathan Corbet
The regex in this block of code makes no sense, and a quick test shows that it never matches anything; simply delete the code. No output changes. Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2025-09-18docs: kdoc: final dump_function() cleanupsJonathan Corbet
Add some more comments to dump_function(), add some comments, and trim out an unneeded duplicate output_declaration() call. Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2025-09-18docs: kdoc: consolidate some of the macro-processing logicJonathan Corbet
The logic to handle macros is split in dump_function(); bring it all together into a single place and add a comment saying what's going on. Remove the unneeded is_define_proto variable, and tighten up the code a bit. Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2025-09-18docs: kdoc: Simplify the dump_function() prototype regexesJonathan Corbet
The regexes for the parsing of function prototypes were more complicated than they needed to be and difficult to understand -- at least, I spent a fair amount of time bashing my head against them. Simplify them, and add some documentation comments as well. Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2025-09-18docs: kdoc: remove a useless empty capture groupJonathan Corbet
The is_define_proto case in dump_function() uses a regex with an empty capture group - () - that has no use; just take it out. Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2025-09-18docs: kdoc: remove a couple of spurious regex charactersJonathan Corbet
The "name" regex in dump_function() includes both the tilde and colon characters, but neither has any place in function prototypes. Remove the characters, after which the regex simplifies to "\w+" No output changes. Signed-off-by: Jonathan Corbet <corbet@lwn.net>
generated by cgit (git 2.34.1) at 2026-01-01 13:36:52 +0000