kernel/linux.git/Documentation/sphinx, branch v6.19.11

Documentation/sphinx/kernel_feat.py: use class directly

2025-11-21T17:32:30+00:00

Now that get_feat is in Python, we don't need to use subprocess to fork an executable file: we can use the feature classes directly. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Message-ID:

tools/docs/get_feat.py: convert get_feat.pl to Python

2025-11-21T17:32:30+00:00

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 Signed-off-by: Jonathan Corbet Message-ID: <03c26cee1ec567804735a33047e625ef5ab7bfa8.1763492868.git.mchehab+huawei@kernel.org>

docs: bring some order to our Python module hierarchy

2025-11-18T16:22:40+00:00

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 Message-ID: <20251110220430.726665-3-corbet@lwn.net>

docs: Move the python libraries to tools/lib/python

2025-11-18T16:22:40+00:00

"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 Message-ID: <20251110220430.726665-2-corbet@lwn.net>

docs: move get_abi.py to tools/docs

2025-10-28T22:01:20+00:00

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 Acked-by: Jani Nikula Signed-off-by: Jonathan Corbet

docs: Move the "features" tools to tools/docs

2025-10-28T22:01:00+00:00

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 Acked-by: Jani Nikula Signed-off-by: Jonathan Corbet

Merge branch 'build-script' into docs-mw

2025-10-17T20:11:30+00:00

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 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.

docs: kernel_include.py: use get_close_matches() to propose alternatives

2025-10-17T19:56:59+00:00

Improve the suggestions algorithm by using get_close_matches() if no suggestions with the same name are found. As we're now building a dict, when the name is identical, but on a different domain, the search is O(1), making it a lot faster. The get_close_matches is also fast, as there is just one loop, instead of 3. This can be useful to detect typos on references, with could be the base of a futuere extension that will handle ref unmatches for the entire build, allowing someone to find typos and fix them. As difflib and get_close_matches are there since the early Python 3.x days, we don't need to handle any extra dependencies to use it. We're keeping the default values for the search, e.g. n=3, cutoff=0.6. With that, we now have things like: $ make SPHINXDIRS="userspace-api/media" htmldocs ... include/uapi/linux/videodev2.h:199: WARNING: Invalid xref: c:type:`v4l2_memory`. Possible alternatives: c:type:`v4l2_meta_format` (from v4l/dev-meta) c:type:`v4l2_rect` (from v4l/dev-overlay) c:type:`v4l2_area` (from v4l/ext-ctrls-image-source) [ref.missing] ... include/uapi/linux/videodev2.h:1985: WARNING: Invalid xref: c:type:`V4L.v4l2_queryctrl`. Possible alternatives: std:label:`v4l2-queryctrl` (from v4l/vidioc-queryctrl) std:label:`v4l2-query-ext-ctrl` (from v4l/vidioc-queryctrl) At the first example, it was not a typo, but a symbol that doesn't seem to be properly documented. The second example points to v4l2-queryctrl, which is a close match for the symbol. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Message-ID: <7365feb74cbdd6b982c87baf5863360ab98cf727.1759329363.git.mchehab+huawei@kernel.org>

tools: docs: parse_data_structs.py: get rid of process_exceptions()

2025-10-17T19:56:59+00:00

Add an extra parameter to parse_file to make it handle exceptions internally, cleaning up the API. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Message-ID: <8575bbc94ff706aa7e7cc3a188399ca17a3169e6.1759329363.git.mchehab+huawei@kernel.org>

docs: kernel_include.py: propose alternatives

2025-10-17T19:56:59+00:00

Specially when using c::namespace, it is not hard to break a reference by forgetting to add a domain. Also, different cases and using "-"/"_" the wrong way are typical cases that people often gets wrong. We might use a more complex logic here to also check for typos, but let's keep it plain, simple. This is enough to get thos exeptions from media controller: .../include/uapi/linux/media.h:26: WARNING: Invalid xref: c:type:`media_device_info`. Possible alternatives: c:type:`MC.media_device_info` (from mediactl/media-ioc-device-info) .../include/uapi/linux/media.h:149: WARNING: Invalid xref: c:type:`media_entity_desc`. Possible alternatives: c:type:`MC.media_entity_desc` (from mediactl/media-ioc-enum-entities) .../include/uapi/linux/media.h:228: WARNING: Invalid xref: c:type:`media_link_desc`. Possible alternatives: c:type:`MC.media_link_desc` (from mediactl/media-ioc-enum-links) .../include/uapi/linux/media.h:235: WARNING: Invalid xref: c:type:`media_links_enum`. Possible alternatives: c:type:`MC.media_links_enum` (from mediactl/media-ioc-enum-links) .../include/uapi/linux/media.h:212: WARNING: Invalid xref: c:type:`media_pad_desc`. Possible alternatives: c:type:`MC.media_pad_desc` (from mediactl/media-ioc-enum-links) .../include/uapi/linux/media.h:298: WARNING: Invalid xref: c:type:`media_v2_entity`. Possible alternatives: c:type:`MC.media_v2_entity` (from mediactl/media-ioc-g-topology) .../include/uapi/linux/media.h:312: WARNING: Invalid xref: c:type:`media_v2_interface`. Possible alternatives: c:type:`MC.media_v2_interface` (from mediactl/media-ioc-g-topology) .../include/uapi/linux/media.h:307: WARNING: Invalid xref: c:type:`media_v2_intf_devnode`. Possible alternatives: c:type:`MC.media_v2_intf_devnode` (from mediactl/media-ioc-g-topology) .../include/uapi/linux/media.h:341: WARNING: Invalid xref: c:type:`media_v2_link`. Possible alternatives: c:type:`MC.media_v2_link` (from mediactl/media-ioc-g-topology) .../include/uapi/linux/media.h:333: WARNING: Invalid xref: c:type:`media_v2_pad`. Possible alternatives: c:type:`MC.media_v2_pad` (from mediactl/media-ioc-g-topology) .../include/uapi/linux/media.h:349: WARNING: Invalid xref: c:type:`media_v2_topology`. Possible alternatives: c:type:`MC.media_v2_topology` (from mediactl/media-ioc-g-topology) Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Message-ID: <4c75d277e950e619ea00ba2dea336853a4aac976.1759329363.git.mchehab+huawei@kernel.org>