Message-ID: <cover.1768488832.git.mchehab+huawei@kernel.org>
Date: Thu, 15 Jan 2026 16:40:21 +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 v2 00/15] Add kernel-doc modules to Documentation/tools

Hi Jon,

On this version, I made it independent from the other series.
As it doesn't touch scripts/kernel-doc, you can apply it without
affecting your renaming series, either before or after your
series.

I added two extra patches on v2 to address Jani's comments. With
that, we now have 3 preparatory patches not directly related to
sphinx.ext.autodoc.

patch 1: a CSS fix to address problems on indexes
patch 2: a variable rename to stop abusing doctree name
patch 3: don't rely on cwd to get Documentation/ location

Starting from patch 4, there is a series of patches fixing,
cleaning up and improving comments inside tools/lib/python/kdoc/.

Except for one patch touching latex_fonts.py, they're optional.
Their focus is mainly to make the comments more uniform at the
docstrings, and ensure that all public vars and methods are
documented.

The final patch creates new *.rst files that points to
the python.lib.kdoc files that we're documenting.

As noticed before, sphinx.ext.autodoc can only document modules
that follows PEP8 and can be imported via "import" or "from"
directive, e.g. all files:

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

Documenting a python file is very simple. All it takes is to
use:

    .. automodule:: lib.python.<dir+name>

Usually, we add a couple of variables to it, to control the
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 is a variant of sphinx-quickstart. The tool seems to
allow generating everything to build it there in separate,
but this didn't work for me.

On this series, I used its output only as a starting example
to ensure that all files from kdoc were added there.

Mauro Carvalho Chehab (15):
  docs: custom.css: prevent li marker to override text
  docs: conf.py: don't use doctree with a different meaning
  docs: conf: don't rely on cwd to get documentation location
  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                       |  23 +--
 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        | 169 +++++++++++---------
 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, 431 insertions(+), 201 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

Powered by blists - more mailing lists