linux-kernel - [PATCH 0/2] Move kernel-doc to tools/docs

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [thread-next>] [day] [month] [year] [list]

Message-ID: <20260114164146.532916-1-corbet@lwn.net>
Date: Wed, 14 Jan 2026 09:41:42 -0700
From: Jonathan Corbet <corbet@....net>
To: linux-doc@...r.kernel.org
Cc: linux-kernel@...r.kernel.org,
	Mauro Carvalho Chehab <mchehab+huawei@...nel.org>,
	Akira Yokosawa <akiyks@...il.com>,
	Shuah Khan <shuah@...nel.org>,
	Jani Nikula <jani.nikula@...ux.intel.com>,
	Jonathan Corbet <corbet@....net>
Subject: [PATCH 0/2] Move kernel-doc to tools/docs

All of the documentation-related tools have been gathered together in
tools/docs, with one exception: kernel-doc still lives under scripts/.
Move it to its proper home, fixing up a fair number of references along the
way.

This move was delayed because it ran afoul of one other relatively recent
change.  With the conversion of kernel-doc to Python, the Sphinx kerneldoc
extension gained the ability to import the relevant modules directly, but
it also kept the option of running kernel-doc as a separate process.  To
decide which course to take, the extension looks at the kerneldoc_bin
configuration setting; if that setting ends with "kernel-doc.py", it
chooses the import method.

Some of us found that behavior a bit obscure.  It also complicated the task
of moving scripts/kernel-doc.py to tools/docs/kernel-doc.  I tried a couple
of ways of preserving this behavior but ended up with solutions that were
just as obscure.

So I took a different approach.  In the end, the ability to run kernel-doc
as a separate process does not buy us much.  For debugging purposes, it's
easier to just run kernel-doc by hand directly.  So this series simply
removes that capability, simplifying the logic and removing a bunch of
code.  The code that creates the command line remains in case anybody
should ever want a specific invocation to run by hand.

Jonathan Corbet (2):
  docs: kdoc: remove support for an external kernel-doc from sphinx
  Move kernel-doc to tools/docs

 Documentation/conf.py                         |  2 +-
 Documentation/doc-guide/kernel-doc.rst        |  8 +--
 Documentation/kbuild/kbuild.rst               |  2 +-
 Documentation/process/coding-style.rst        |  2 +-
 Documentation/sphinx/kerneldoc.py             | 53 +++----------------
 .../it_IT/doc-guide/kernel-doc.rst            |  8 +--
 .../sp_SP/process/coding-style.rst            |  2 +-
 .../zh_CN/doc-guide/kernel-doc.rst            | 10 ++--
 .../translations/zh_CN/kbuild/kbuild.rst      |  2 +-
 .../zh_CN/process/coding-style.rst            |  2 +-
 .../zh_TW/process/coding-style.rst            |  2 +-
 MAINTAINERS                                   |  2 -
 Makefile                                      |  2 +-
 drivers/gpu/drm/i915/Makefile                 |  2 +-
 scripts/kernel-doc                            |  1 -
 tools/docs/find-unused-docs.sh                |  2 +-
 .../kernel-doc.py => tools/docs/kernel-doc    |  0
 tools/docs/sphinx-build-wrapper               |  2 +-
 18 files changed, 30 insertions(+), 74 deletions(-)
 delete mode 120000 scripts/kernel-doc
 rename scripts/kernel-doc.py => tools/docs/kernel-doc (100%)

-- 
2.52.0