Skip to content

Add kernel-doc modules to Documentation/tools

Mauro Carvalho Chehab linux-doc lkml 2 versions – New

Get series with b4
b4 am [email protected]

Versions newest first · linked by author and title

  1. v2 Latest15 patches 0 repliesNew
  2. v113 patches 9 repliesSuperseded

Patches in v2 No applies recorded yet

#Subject and filesSizeRepliesApplied
1/15docs: custom.css: prevent li marker to override textDocumentation/sphinx-static/custom.css+3 -00 replies
2/15docs: conf.py: don't use doctree with a different meaningDocumentation/conf.py+4 -40 replies
3/15docs: conf: don't rely on cwd to get documentation locationDocumentation/conf.py+5 -70 replies
4/15docs: enable Sphinx autodoc extension to allow documenting pythonDocumentation/conf.py+5 -00 replies
5/15docs: custom.css: add CSS for pythonDocumentation/sphinx-static/custom.css+9 -00 replies
6/15docs: kdoc: latex_fonts: Improve docstrings and commentstools/lib/python/kdoc/latex_fonts.py+56 -390 replies
7/15docs: kdoc_files: Improve docstrings and commentstools/lib/python/kdoc/kdoc_files.py+12 -110 replies
8/15docs: kdoc_item: Improve docstrings and commentstools/lib/python/kdoc/kdoc_item.py+18 -00 replies
9/15docs: kdoc_parser: Improve docstrings and commentstools/lib/python/kdoc/kdoc_parser.py+92 -770 replies
10/15docs: kdoc_output: Improve docstrings and commentstools/lib/python/kdoc/kdoc_output.py+35 -250 replies
11/15docs: kdoc_re: Improve docstrings and commentstools/lib/python/kdoc/kdoc_re.py+11 -70 replies
12/15docs: kdoc: parse_data_structs: Improve docstrings and commentstools/lib/python/kdoc/parse_data_structs.py+39 -230 replies
13/15docs: kdoc: enrich_formatter: Improve docstrings and commentstools/lib/python/kdoc/enrich_formatter.py+15 -50 replies
14/15docs: kdoc: python_version: Improve docstrings and commentstools/lib/python/kdoc/python_version.py+16 -40 replies
15/15docs: add kernel-doc modules documentationDocumentation/tools/index.rst Documentation/tools/kdoc.rst Documentation/tools/kdoc_ancillary.rst +3 more+112 -00 replies

Reviews trailers per patch

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

Read the v2 thread

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