Mauro's work to include documentation from our Python modules. His cover
letter follows:
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.
The parsing of jobserver options is done in a massive try: block that hides
problems and (perhaps) bugs. Split up that block and make the logic
explicit by moving the initial parsing of MAKEFLAGS out of that block. Add
warnings in the places things can go wrong.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Changeset 469c1c9eb6 ("kernel-doc: Issue warnings that were silently discarded")
didn't properly addressed the missing messages behavior, as
it was calling directly python logger low-level function,
instead of using the expected method to emit warnings.
Basically, there are two methods to log messages:
- self.config.log.warning() - This is the raw level to emit a
warning. It just writes the a message at stderr, via python
logging, as it is initialized as:
self.config.log = logging.getLogger("kernel-doc")
- self.config.warning() - This is where we actually consider a
message as a warning, properly incrementing error count.
Due to that, several parsing error messages are internally considered
as success, causing -Werror to not work on such messages.
While here, ensure that the last ignored entry will also be handled
by adding an extra check at the end of the parse handler.
Fixes: 469c1c9eb6 ("kernel-doc: Issue warnings that were silently discarded")
Closes: https://lore.kernel.org/linux-doc/20260112091053.00cee29a@foz.lan/
Cc: stable@vger.kernel.org
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Acked-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <95109a6585171da4d6900049deaa2634b41ee743.1768823489.git.mchehab+huawei@kernel.org>
When using GNU Make's jobserver feature in kernel builds, a bug in MAKEFLAGS
propagation caused "--jobserver-auth=r,w" to reference an unintended file
descriptor. This led to infinite loops in jobserver-exec's os.read() calls
due to empty token.
My shell opened /etc/passwd for some reason without closing it, and as a
result, all child processes inherited this fd 3.
$ ls -l /proc/self/fd
total 0
lrwx------ 1 changbin changbin 64 Dec 25 13:03 0 -> /dev/pts/1
lrwx------ 1 changbin changbin 64 Dec 25 13:03 1 -> /dev/pts/1
lrwx------ 1 changbin changbin 64 Dec 25 13:03 2 -> /dev/pts/1
lr-x------ 1 changbin changbin 64 Dec 25 13:03 3 -> /etc/passwd
lr-x------ 1 changbin changbin 64 Dec 25 13:03 4 -> /proc/1421383/fd
In this case, the `make` should open a new file descriptor for jobserver
control, but clearly, it did not do so and instead still passed fd 3 as
"--jobserver-auth=3,4" in MAKEFLAGS. (The version of my gnu make is 4.3)
This update ensures robustness against invalid jobserver configurations,
even when `make` incorrectly pass non-pipe file descriptors.
* Rejecting empty reads to prevent infinite loops on EOF.
* Clearing `self.jobs` to avoid writing to incorrect files if invalid tokens
are detected.
* Printing detailed error messages to stderr to inform the user.
Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Changbin Du <changbin.du@huawei.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260108113836.2976527-1-changbin.du@huawei.com>
Inline kernel-doc blocks failed to parse tags containing dots (e.g.
creator.process_name in panfrost_gem.h) because the @name regex only
matched word characters. Modify the single-line pattern to match
doc_inline_sect so it includes \. and parses the same as a multi-line
comment.
Signed-off-by: Steven Price <steven.price@arm.com>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251211104851.45330-1-steven.price@arm.com>
kdoc is looking for "@value" here, so use that kind of string in the
warning message. The "%value" can be confusing.
This changes:
Warning: drivers/net/wireless/mediatek/mt76/testmode.h:92 Excess enum value '%MT76_TM_ATTR_TX_PENDING' description in 'mt76_testmode_attr'
to this:
Warning: drivers/net/wireless/mediatek/mt76/testmode.h:92 Excess enum value '@MT76_TM_ATTR_TX_PENDING' description in 'mt76_testmode_attr'
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251126061752.3497106-1-rdunlap@infradead.org>
Recognize and ignore __rcu (in struct members), __private (in struct
members), and __always_unused (in function parameters) to prevent
kernel-doc warnings:
Warning: include/linux/rethook.h:38 struct member 'void (__rcu *handler' not described in 'rethook'
Warning: include/linux/hrtimer_types.h:47 Invalid param: enum hrtimer_restart (*__private function)(struct hrtimer *)
Warning: security/ipe/hooks.c:81 function parameter '__always_unused' not described in 'ipe_mmap_file'
Warning: security/ipe/hooks.c:109 function parameter '__always_unused' not described in 'ipe_file_mprotect'
There are more of these (in compiler_types.h, compiler_attributes.h)
that can be added as needed.
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251127063117.150384-1-rdunlap@infradead.org>
As we want to call Python code directly at the Sphinx extension,
convert get_feat.pl to Python.
The code was made to be (almost) bug-compatible with the Perl
version, with two exceptions:
1. Currently, Perl script outputs a wrong table if arch is set
to a non-existing value;
2. the ReST table output when --feat is used without --arch
has an invalid format, as the number of characters for the
table delimiters are wrong.
Those two bugs were fixed while testing the conversion.
Additionally, another caveat was solved:
the output when --feat is used without arch and the feature
doesn't exist doesn't contain an empty table anymore.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <03c26cee1ec567804735a33047e625ef5ab7bfa8.1763492868.git.mchehab+huawei@kernel.org>
Now that we have tools/lib/python for our Python modules, turn them into
proper packages with a single namespace so that everything can just use
tools/lib/python in sys.path. No functional change.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251110220430.726665-3-corbet@lwn.net>
"scripts/lib" was always a bit of an awkward place for Python modules. We
already have tools/lib; create a tools/lib/python, move the libraries
there, and update the users accordingly.
While at it, move the contents of tools/docs/lib. Rather than make another
directory, just put these documentation-oriented modules under "kdoc".
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251110220430.726665-2-corbet@lwn.net>
