kernel/linux.git/Documentation/doc-guide, 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>

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>

doc-guide: kernel-doc: specify that W=n does not check header files

2026-01-06T21:42:31+00:00

The documentation states that: make W=n can be used to verify the documentation format. This is true for .c files but not for headers [1]. Modify the documentation to specify that headers files are not covered by make W=n and that these need to be checked separately with scripts/kernel-doc. [1] commit 3a025e1d1c2e ("Add optional check for bad kernel-doc comments") Link: https://git.kernel.org/torvalds/c/3a025e1d1c2e Signed-off-by: Vincent Mailhol Signed-off-by: Jonathan Corbet Message-ID: <20251225-doc-format-check-v1-1-dff637a4d275@kernel.org>

docs: kernel-doc.rst: document the new "var" kernel-doc markup

2025-12-22T21:43:25+00:00

Add a description containing the new syntax to document variables within kernel-doc markups. Reviewed-by: Randy Dunlap Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Message-ID:

docs: kernel-doc.rst: don't let automarkup mangle with consts

2025-12-22T21:43:25+00:00

This document contains several words that tricks automarkup. Ensure that all of them will be inside a ``const`` markup, avoiding automarkup to touch them. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Randy Dunlap Signed-off-by: Jonathan Corbet Message-ID:

docs: parse-headers.rst: Fix a typo

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

Replace "vantage" with "advantage" in the description of userspace API cross-references. Signed-off-by: Ankit Khushwaha Signed-off-by: Jonathan Corbet Message-ID: <20251115114233.32239-1-ankitkhushwaha.linux@gmail.com>

docs: parse-headers.rst: remove uneeded parenthesis

2025-11-13T16:34:40+00:00

As pointed by Randy, the parenthesis there is not needed and it violates the document coding style. Reported-by: Randy Dunlap Closes: https://lore.kernel.org/linux-doc/9d709020-03fe-467c-be7f-d5ee251bb79a@infradead.org/ Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Message-ID:

docs: doc-guide: parse-headers.rst update its documentation

2025-11-10T19:40:54+00:00

Besides converting from Perl to Python, parse-headers has gained some new functionality and was moved to tools/docs. Update its documentation accordingly. Reported-by: Randy Dunlap Closes: https://lore.kernel.org/linux-doc/9391a0f0-7c92-42aa-8190-28255b22e131@infradead.org/ Acked-by: Randy Dunlap Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Dongliang Mu Signed-off-by: Jonathan Corbet Message-ID: <1f9025dc98dc58da3cc31f3343d5027f351be338.1762594622.git.mchehab+huawei@kernel.org>

doc-guide: kernel-doc: add %CONST examples

2025-11-05T18:27:12+00:00

Add examples of using '%' for formatting constant values to facilitate more usage of "%CONST" in kernel-doc. Suggested-by: Tony Luck Signed-off-by: Randy Dunlap Signed-off-by: Jonathan Corbet Message-ID: <20251104050930.720711-1-rdunlap@infradead.org>

docs: move find-unused-docs.sh to tools/docs

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

...and update references accordingly. Reviewed-by: Mauro Carvalho Chehab Acked-by: Jani Nikula Signed-off-by: Jonathan Corbet