linux-kernel - [PATCH 00/13] Add kernel-doc modules to Documentation/tools

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: <cover.1768396023.git.mchehab+huawei@kernel.org>
Date: Wed, 14 Jan 2026 14:17:13 +0100
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Jonathan Corbet <corbet@....net>
Cc: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>,
	linux-doc@...r.kernel.org,
	linux-kernel@...r.kernel.org,
	Nícolas F. R. A. Prado <nfraprado@...labora.com>,
	Randy Dunlap <rdunlap@...radead.org>,
	Shuah Khan <skhan@...uxfoundation.org>
Subject: [PATCH 00/13] Add kernel-doc modules to Documentation/tools

Hi Jon,

This is the splitted version of my RFC to use sphinx.ext.autodoc
to document kernel-doc modules. It documents only kernel-doc
modules, but, once we merge it, we can document other things.

This series comes after:
    https://lore.kernel.org/linux-doc/cover.1768395332.git.mchehab+huawei@kernel.org/T/#t

patch 1 is actually not directly related: if fixes a bug I noticed
on Sphinx indexes with a large maxdepth;

patch 2 adds sphinx.ext.autodoc and place the directories where
python modules can be found. It doesn't use the extension, though.
This will happen only at the final patch;

patches 3 to 12 are basically documentation cleanups and fixes that
ensure that the documentation will be complete.

patch 13 creates new *.rst files that points to python.lib.kdoc
files.

With this version, python files inside tools/ or scripts/
can be documented, but there is a catch (probably due to PEP8):

    - files must end with ".py"
    - file names can't have "-".

So, unfortunately, we can't document kernel-doc.py, except if
we rename it to kernel_doc.py.

As I mentioned at RFC, we could use:

    $ sphinx-apidoc scripts tools -o foobar
    $ sphinx-apidoc tools/docs -o foobar
    ...

to generate .rst skeletons with the modules to be added, but
manual work is needed afterwards.

Mauro Carvalho Chehab (13):
  docs: custom.css: prevent li marker to override text
  docs: enable Sphinx autodoc extension to allow documenting python
  docs: custom.css: add CSS for python
  docs: kdoc: latex_fonts: Improve docstrings and comments
  docs: kdoc_files: Improve docstrings and comments
  docs: kdoc_item: Improve docstrings and comments
  docs: kdoc_parser: Improve docstrings and comments
  docs: kdoc_output: Improve docstrings and comments
  docs: kdoc_re: Improve docstrings and comments
  docs: kdoc: parse_data_structs: Improve docstrings and comments
  docs: kdoc: enrich_formatter: Improve docstrings and comments
  docs: kdoc: python_version: Improve docstrings and comments
  docs: add kernel-doc modules documentation

 Documentation/conf.py                       |  11 +-
 Documentation/sphinx-static/custom.css      |  12 ++
 Documentation/tools/index.rst               |   1 +
 Documentation/tools/kdoc.rst                |  12 ++
 Documentation/tools/kdoc_ancillary.rst      |  46 +++++
 Documentation/tools/kdoc_output.rst         |  14 ++
 Documentation/tools/kdoc_parser.rst         |  29 ++++
 Documentation/tools/python.rst              |  10 ++
 tools/lib/python/kdoc/enrich_formatter.py   |  20 ++-
 tools/lib/python/kdoc/kdoc_files.py         |  23 +--
 tools/lib/python/kdoc/kdoc_item.py          |  18 ++
 tools/lib/python/kdoc/kdoc_output.py        |  60 ++++---
 tools/lib/python/kdoc/kdoc_parser.py        | 175 +++++++++++---------
 tools/lib/python/kdoc/kdoc_re.py            |  18 +-
 tools/lib/python/kdoc/latex_fonts.py        |  95 ++++++-----
 tools/lib/python/kdoc/parse_data_structs.py |  62 ++++---
 tools/lib/python/kdoc/python_version.py     |  20 ++-
 17 files changed, 430 insertions(+), 196 deletions(-)
 create mode 100644 Documentation/tools/kdoc.rst
 create mode 100644 Documentation/tools/kdoc_ancillary.rst
 create mode 100644 Documentation/tools/kdoc_output.rst
 create mode 100644 Documentation/tools/kdoc_parser.rst
 create mode 100644 Documentation/tools/python.rst

-- 
2.52.0