Add kernel-doc modules to Documentation/tools
Get series with b4
b4 am [email protected]Versions newest first · linked by author and title
- v2 Latest15 patches 0 repliesNew
- v113 patches 9 repliesSuperseded
Patches in v2 No applies recorded yet
| # | Subject and files | Size | Replies | Applied |
|---|---|---|---|---|
| 1/15 | docs: custom.css: prevent li marker to override textDocumentation/ | +3 | 0 replies | |
| 2/15 | docs: conf.py: don't use doctree with a different meaningDocumentation/ | +4 | 0 replies | |
| 3/15 | docs: conf: don't rely on cwd to get documentation locationDocumentation/ | +5 | 0 replies | |
| 4/15 | docs: enable Sphinx autodoc extension to allow documenting pythonDocumentation/ | +5 | 0 replies | |
| 5/15 | docs: custom.css: add CSS for pythonDocumentation/ | +9 | 0 replies | |
| 6/15 | docs: kdoc: latex_fonts: Improve docstrings and commentstools/ | +56 | 0 replies | |
| 7/15 | docs: kdoc_files: Improve docstrings and commentstools/ | +12 | 0 replies | |
| 8/15 | docs: kdoc_item: Improve docstrings and commentstools/ | +18 | 0 replies | |
| 9/15 | docs: kdoc_parser: Improve docstrings and commentstools/ | +92 | 0 replies | |
| 10/15 | docs: kdoc_output: Improve docstrings and commentstools/ | +35 | 0 replies | |
| 11/15 | docs: kdoc_re: Improve docstrings and commentstools/ | +11 | 0 replies | |
| 12/15 | docs: kdoc: parse_data_structs: Improve docstrings and commentstools/ | +39 | 0 replies | |
| 13/15 | docs: kdoc: enrich_formatter: Improve docstrings and commentstools/ | +15 | 0 replies | |
| 14/15 | docs: kdoc: python_version: Improve docstrings and commentstools/ | +16 | 0 replies | |
| 15/15 | docs: add kernel-doc modules documentationDocumentation/ Documentation/ Documentation/ +3 more | +112 | 0 replies |
Reviews trailers per patch
No Reviewed-by, Acked-by or Tested-by trailers for v2 yet.
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