kernel/linux.git/Documentation/conf.py, branch v7.0-rc7

Documentation: use a source-read extension for the index link boilerplate

2026-01-23T18:59:34+00:00

The root document usually has a special :ref:`genindex` link to the generated index. This is also the case for Documentation/index.rst. The other index.rst files deeper in the directory hierarchy usually don't. For SPHINXDIRS builds, the root document isn't Documentation/index.rst, but some other index.rst in the hierarchy. Currently they have a ".. only::" block to add the index link when doing SPHINXDIRS html builds. This is obviously very tedious and repetitive. The link is also added to all index.rst files in the hierarchy for SPHINXDIRS builds, not just the root document. Put the boilerplate in a sphinx-includes/subproject-index.rst file, and include it at the end of the root document for subproject builds in an ad-hoc source-read extension defined in conf.py. For now, keep having the boilerplate in translations, because this approach currently doesn't cover translated index link headers. Cc: Jonathan Corbet Cc: Mauro Carvalho Chehab Cc: Randy Dunlap Signed-off-by: Jani Nikula Tested-by: Mauro Carvalho Chehab Reviewed-by: Mauro Carvalho Chehab [jc: did s/doctree/kern_doc_dir/ ] Signed-off-by: Jonathan Corbet Message-ID: <20260123143149.2024303-1-jani.nikula@intel.com>

Merge branch 'mauro' into docs-mw

2026-01-23T18:46:08+00:00

Mauro's work to include documentation from our Python modules. His cover letter follows: This is an extended version of: https://lore.kernel.org/linux-doc/cover.1768488832.git.mchehab+huawei@kernel.org/ It basically adds everything we currently have inside libs/tool/python to "tools" book inside documentation. This version should be independent of the other series yet to be merged, (including the jobserver one). The vast amount of changes here are docstring cleanups and additions. They mainly consists on: - ensuring that every phrase will end with a period, making it uniform along all files; - cleaning ups to better uniform docstrings; - variable descriptions now use "#:" markup, as it allows autodoc to add them inside the documentation; - added some missing docstrings; - some new blank lines at comments to make ReST syntax parser happy; - add a couple of sphinx markups (mainly, code blocks). Most of those are minor changes, affecting only comments. It also has one patch per libarary type, adding them to docs. For kernel-doc, I did the cleanups first, as there is one code block inside tools/lib/python/kdoc/latex_fonts.py that would cause a Sphinx crash without such markups. The series actually starts with 3 fixes: - avoid "*" markups on indexes with deep> 3 to override text - a variable rename to stop abusing doctree name - don't rely on cwd to get Documentation/ location patch 4 adds support to document scripts either at: - tools/ - scripts/ patch 5 contains a CSS to better display autodoc html output. For those who want to play with documentation, documenting a python file is very simple. All it takes is to use: .. automodule:: lib.python. Usually, we add a couple of control members to it to adjust the desired documentation scope (add/remove members, showing class inheritance, showing members that currently don't have docstrings, etc). That's why we're using: .. automodule:: lib.python.kdoc.enrich_formatter :members: :show-inheritance: :undoc-members: (and similar) inside tools/kdoc*.rst. autodoc allows filtering in/out members, file docstrings, etc. It also allows documenting just some members or functions with directives like: ..autofunction: ..automember: Sphinx also has a helper script to generate .rst files with documentation: $ sphinx-apidoc -o foobar tools/lib/python/ which can be helpful to discover what should be documented, although changes are needed to use what it produces.

docs: enable Sphinx autodoc extension to allow documenting python

2026-01-23T18:37:38+00:00

Adding python documentation is simple with Sphinx: all we need is to include the ext.autodoc extension and add the directories where the Python code sits at the sys.path. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Message-ID: <29cbe375dc418d6fa5793f55199799b5b52dcd38.1768838938.git.mchehab+huawei@kernel.org>

docs: conf: don't rely on cwd to get documentation location

2026-01-23T18:37:38+00:00

Instead of relying that Sphinx will be called from Documentation/ dir, pick the location based on __file__. Suggested-by: Jani Nikula Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Message-ID: <34c38718dfade91ff6f7afca5e9c1705ba253c97.1768838938.git.mchehab+huawei@kernel.org>

docs: conf.py: don't use doctree with a different meaning

2026-01-23T18:37:38+00:00

At Sphinx, doctree is a directory where doc build cache is stored. Use a better name. No functional changes. Suggested-by: Jani Nikula Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Message-ID:

docs: conf.py: get rid of the now unused kerneldoc_bin env var

2026-01-20T22:31:06+00:00

In the past, this contained the location of the binary file to parse kernel-doc. Nowadays, it is used only for debugging purposes, inside kerneldoc.py extension. Move it to sphinx/kerneldoc.py, to avoid needing to handle with it on several places. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Message-ID:

docs: kdoc: move kernel-doc to tools/docs

2026-01-20T22:31:06+00:00

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: Link man pages to https://man7.org/

2026-01-16T18:19:06+00:00

Configure manpages_url to link man pages to https://man7.org/. https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-manpages_url Acked-by: Alejandro Colomar Signed-off-by: Petr Vorel Signed-off-by: Jonathan Corbet Message-ID: <20260113113612.315748-3-pvorel@suse.cz>

docs: conf.py: get rid of load_config.py

2025-09-21T22:40:37+00:00

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 Signed-off-by: Jonathan Corbet Message-ID:

docs: conf.py: drop xindy rule

2025-08-29T22:45:09+00:00

The rule as-is is wrong, as it was inverted. Besides that, after retest building all repos with suggested LaTeX packages given by sphinx-pre-install, I was unable to reproduce the issues I saw with xindy in the past. So, let's just drop. If anyone reports issues with xindy, we may need to readd, but at the right way, e.g. {options}{pkgname}. Reported-by: Akira Yokosawa Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/83068bc31839e7095f1f408e49658362d467797e.1756123459.git.mchehab+huawei@kernel.org