Skip to content

Add tools/lib/python modules to Documentation/tools

Mauro Carvalho Chehab linux-doc lkml 1 version In review

Get series with b4
b4 am [email protected]

Versions newest first

  1. v1 Latest25 patches 3 repliesIn review

Patches in v1 No applies recorded yet

#Subject and filesSizeRepliesApplied
1/25docs: custom.css: prevent li marker to override textDocumentation/sphinx-static/custom.css+3 -00 replies
2/25docs: conf.py: don't use doctree with a different meaningDocumentation/conf.py+4 -40 replies
3/25docs: conf: don't rely on cwd to get documentation locationDocumentation/conf.py+5 -70 replies
4/25docs: enable Sphinx autodoc extension to allow documenting pythonDocumentation/conf.py+5 -00 replies
5/25docs: custom.css: add CSS for pythonDocumentation/sphinx-static/custom.css+9 -00 replies
6/25docs: kdoc: latex_fonts: Improve docstrings and commentstools/lib/python/kdoc/latex_fonts.py+56 -390 replies
7/25docs: kdoc_files: Improve docstrings and commentstools/lib/python/kdoc/kdoc_files.py+12 -110 replies
8/25docs: kdoc_item: Improve docstrings and commentstools/lib/python/kdoc/kdoc_item.py+18 -00 replies
9/25docs: kdoc_parser: Improve docstrings and commentstools/lib/python/kdoc/kdoc_parser.py+92 -770 replies
10/25docs: kdoc_output: Improve docstrings and commentstools/lib/python/kdoc/kdoc_output.py+35 -250 replies
11/25docs: kdoc_re: Improve docstrings and commentstools/lib/python/kdoc/kdoc_re.py+11 -70 replies
12/25docs: kdoc: parse_data_structs: Improve docstrings and commentstools/lib/python/kdoc/parse_data_structs.py+39 -230 replies
13/25docs: kdoc: enrich_formatter: Improve docstrings and commentstools/lib/python/kdoc/enrich_formatter.py+15 -50 replies
14/25docs: kdoc: python_version: Improve docstrings and commentstools/lib/python/kdoc/python_version.py+16 -40 replies
15/25docs: add kernel-doc modules documentationDocumentation/tools/index.rst Documentation/tools/kdoc.rst Documentation/tools/kdoc_ancillary.rst +3 more+112 -00 replies
16/25docs: add kabi modules documentationDocumentation/tools/kabi.rst Documentation/tools/kabi_helpers.rst Documentation/tools/kabi_parser.rst +3 more+55 -00 replies
17/25docs: python: abi_parser: do some improvements at documentationtools/lib/python/abi/abi_parser.py+18 -150 replies
18/25docs: python: abi_regex: do some improvements at documentationtools/lib/python/abi/abi_regex.py+20 -60 replies
19/25docs: kabi: system_symbols: end docstring phrases with a dottools/lib/python/abi/system_symbols.py+7 -70 replies
20/25docs: kabi: helpers: add helper for debug bits 7 and 8tools/lib/python/abi/helpers.py+2 -00 replies
21/25docs: kabi: helpers: add documentation for each "enum" valuetools/lib/python/abi/helpers.py+20 -200 replies
22/25docs: add jobserver module documentationDocumentation/tools/jobserver.rst Documentation/tools/python.rst+11 -00 replies
23/25docs: jobserver: do some documentation improvementstools/lib/python/jobserver.py+12 -80 replies
24/25docs: add parse_features module documentationDocumentation/tools/feat.rst Documentation/tools/python.rst+11 -00 replies
25/25docs: parse_features: make documentation more consistenttools/lib/python/feat/parse_features.py+20 -70 replies

Reviews trailers per patch

No Reviewed-by, Acked-by or Tested-by trailers for v1 yet.

Read the v1 thread

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

Hi Jon,

This is an extended version of:

    https://lore.kernel.org/linux-doc/[email protected]/

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
Signature · 1 line
2.52.0