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

[Mauro Carvalho Chehab]

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@xxxxxxxxxx/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