[PATCH 00/25] Add tools/lib/python modules to Documentation/tools

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

Hi Jon,

This is an extended version of:
    https://lore.kernel.org/linux-doc/cover.1768488832.git.mchehab+huawei@kernel.org/

It basically adds everything we currently have inside libs/tool/python
to "tools" book inside documentation.

This version should be independent of the other series yet to be merged,
(including the jobserver one).

The vast amount of changes here are docstring cleanups and additions.
They mainly consists on:

- ensuring that every phrase will end with a period, making it uniform
  along all files;
- cleaning ups to better uniform docstrings;
- variable descriptions now use "#:" markup, as it allows autodoc to
  add them inside the documentation;
- added some missing docstrings;
- some new blank lines at comments to make ReST syntax parser happy;
- add a couple of sphinx markups (mainly, code blocks).

Most of those are minor changes, affecting only comments.

It also has one patch per libarary type, adding them to docs.

For kernel-doc, I did the cleanups first, as there is one code block
inside tools/lib/python/kdoc/latex_fonts.py that would cause a Sphinx
crash without such markups.

The series actually starts with 3 fixes:

- avoid "*" markups on indexes with deep> 3 to override text
- a variable rename to stop abusing doctree name
- don't rely on cwd to get Documentation/ location

patch 4 adds support to document scripts either at:
    - tools/
    - scripts/

patch 5 contains a CSS to better display autodoc html output.

For those who want to play with documentation, documenting a python
file is very simple. All it takes is to use:

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

Usually, we add a couple of control members to it to adjust
the desired 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 can be helpful to discover what should be documented,
although changes are needed to use what it produces.

Mauro Carvalho Chehab (25):
  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
  docs: add kabi modules documentation
  docs: python: abi_parser: do some improvements at documentation
  docs: python: abi_regex: do some improvements at documentation
  docs: kabi: system_symbols: end docstring phrases with a dot
  docs: kabi: helpers: add helper for debug bits 7 and 8
  docs: kabi: helpers: add documentation for each "enum" value
  docs: add jobserver module documentation
  docs: jobserver: do some documentation improvements
  docs: add parse_features module documentation
  docs: parse_features: make documentation more consistent

 Documentation/conf.py                       |  23 +--
 Documentation/sphinx-static/custom.css      |  12 ++
 Documentation/tools/feat.rst                |  10 ++
 Documentation/tools/index.rst               |   1 +
 Documentation/tools/jobserver.rst           |  10 ++
 Documentation/tools/kabi.rst                |  13 ++
 Documentation/tools/kabi_helpers.rst        |  11 ++
 Documentation/tools/kabi_parser.rst         |  10 ++
 Documentation/tools/kabi_regex.rst          |  10 ++
 Documentation/tools/kabi_symbols.rst        |  10 ++
 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              |  13 ++
 tools/lib/python/abi/abi_parser.py          |  33 ++--
 tools/lib/python/abi/abi_regex.py           |  26 ++-
 tools/lib/python/abi/helpers.py             |  42 ++---
 tools/lib/python/abi/system_symbols.py      |  14 +-
 tools/lib/python/feat/parse_features.py     |  27 +++-
 tools/lib/python/jobserver.py               |  20 ++-
 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 ++-
 30 files changed, 607 insertions(+), 264 deletions(-)
 create mode 100644 Documentation/tools/feat.rst
 create mode 100644 Documentation/tools/jobserver.rst
 create mode 100644 Documentation/tools/kabi.rst
 create mode 100644 Documentation/tools/kabi_helpers.rst
 create mode 100644 Documentation/tools/kabi_parser.rst
 create mode 100644 Documentation/tools/kabi_regex.rst
 create mode 100644 Documentation/tools/kabi_symbols.rst
 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