Merge tag 'docs-6.16' of git://git.lwn.net/linux

Pull documentation updates from Jonathan Corbet:
"A moderately busy cycle for documentation this time around:

- The most significant change is t

Merge tag 'docs-6.16' of git://git.lwn.net/linux

Pull documentation updates from Jonathan Corbet:
"A moderately busy cycle for documentation this time around:

- The most significant change is the replacement of the old
kernel-doc script (a monstrous collection of Perl regexes that
predates the Git era) with a Python reimplementation. That, too, is
a horrifying collection of regexes, but in a much cleaner and more
maintainable structure that integrates far better with the Sphinx
build system.

This change has been in linux-next for the full 6.15 cycle; the
small number of problems that turned up have been addressed,
seemingly to everybody's satisfaction. The Perl kernel-doc script
remains in tree (as scripts/kernel-doc.pl) and can be used with a
command-line option if need be. Unless some reason to keep it
around materializes, it will probably go away in 6.17.

Credit goes to Mauro Carvalho Chehab for doing all this work.

- Some RTLA documentation updates

- A handful of Chinese translations

- The usual collection of typo fixes, general updates, etc"

* tag 'docs-6.16' of git://git.lwn.net/linux: (85 commits)
Docs: doc-guide: update sphinx.rst Sphinx version number
docs: doc-guide: clarify latest theme usage
Documentation/scheduler: Fix typo in sched-stats domain field description
scripts: kernel-doc: prevent a KeyError when checking output
docs: kerneldoc.py: simplify exception handling logic
MAINTAINERS: update linux-doc entry to cover new Python scripts
docs: align with scripts/syscall.tbl migration
Documentation: NTB: Fix typo
Documentation: ioctl-number: Update table intro
docs: conf.py: drop backward support for old Sphinx versions
Docs: driver-api/basics: add kobject_event interfaces
Docs: relay: editing cleanups
docs: fix "incase" typo in coresight/panic.rst
Fix spelling error for 'parallel'
docs: admin-guide: fix typos in reporting-issues.rst
docs: dmaengine: add explanation for DMA_ASYNC_TX capability
Documentation: leds: improve readibility of multicolor doc
docs: fix typo in firmware-related section
docs: Makefile: Inherit PYTHONPYCACHEPREFIX setting as env variable
Documentation: ioctl-number: Update outdated submission info
...

show more ...

scripts/lib/kdoc/kdoc_parser.py: move kernel entry to a class

The KernelDoc class is too complex. Start optimizing it by
placing the kernel-doc parser entry to a separate class.

Signed-off-by: Maur

scripts/lib/kdoc/kdoc_parser.py: move kernel entry to a class

The KernelDoc class is too complex. Start optimizing it by
placing the kernel-doc parser entry to a separate class.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <28b456f726a022011f0ce5810dbcc26827c1403a.1745564565.git.mchehab+huawei@kernel.org>

show more ...

scripts/lib/kdoc: change mode to 0644

The script library here contain just classes. Remove execution
permission.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jona

scripts/lib/kdoc: change mode to 0644

The script library here contain just classes. Remove execution
permission.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <be0b0a5bde82fa09027a5083f8202f150581eb4e.1745564565.git.mchehab+huawei@kernel.org>

show more ...

scripts/lib/kdoc/kdoc_parser.py: move states to a separate class

States are really enums. on Python, enums are actually classes,
as can be seen at:
https://docs.python.org/3/library/enum.html

Yet,

scripts/lib/kdoc/kdoc_parser.py: move states to a separate class

States are really enums. on Python, enums are actually classes,
as can be seen at:
https://docs.python.org/3/library/enum.html

Yet, I can't see any advantage of derivating the class from
enum class here. So, just place the states on a separate class.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/00cb4e0b8a1545bf7c4401b58213841db5cba2e2.1744685912.git.mchehab+huawei@kernel.org

show more ...

Merge branch 'mauro' into docs-mw

Mauro says:

This changeset contains the kernel-doc.py script to replace the verable
kernel-doc originally written in Perl. It replaces the first version and the
se

Merge branch 'mauro' into docs-mw

Mauro says:

This changeset contains the kernel-doc.py script to replace the verable
kernel-doc originally written in Perl. It replaces the first version and the
second series I sent on the top of it.

I tried to stay as close as possible of the original Perl implementation
on the first patch introducing kernel-doc.py, as it helps to double check
if each function was properly translated to Python. This have been
helpful debugging troubles that happened during the conversion.

I worked hard to make it bug-compatible with the original one. Still, its
output has a couple of differences from the original one:

- The tab expansion works better with the Python script. With that, some
outputs that contain tabs at kernel-doc markups are now different;

- The new script works better stripping blank lines. So, there are a couple
of empty new lines that are now stripped with this version;

- There is a buggy logic at kernel-doc to strip empty description and
return sections. I was not able to replicate the exact behavior. So, I ended
adding an extra logic to strip empty sections with a different algorithm.

Yet, on my tests, the results are compatible with the venerable script
output for all .. kernel-doc tags found in Documentation/. I double-checked
this by adding support to output the kernel-doc commands when V=1, and
then I ran a diff between kernel-doc.pl and kernel-doc.py for the same
command lines.

The only patch that doesn't belong to this series is a patch dropping
kernel-doc.pl. I opted to keep it for now, as it can help to better
test the new tools.

With such changes, if one wants to build docs with the old script,
all it is needed is to use KERNELDOC parameter, e.g.:

$ make KERNELDOC=scripts/kernel-doc.pl htmldocs

show more ...

scripts: kernel-doc: fix parsing function-like typedefs (again)

Typedefs like

typedef struct phylink_pcs *(*pcs_xlate_t)(const u64 *args);

have a typedef_type that ends with a * and therefore

scripts: kernel-doc: fix parsing function-like typedefs (again)

Typedefs like

typedef struct phylink_pcs *(*pcs_xlate_t)(const u64 *args);

have a typedef_type that ends with a * and therefore has no word
boundary. Add an extra clause for the final group of the typedef_type so
we only require a word boundary if we match a word.

[mchehab: modify also kernel-doc.py, as we're deprecating the perl version]

Fixes: 7d2c6b1edf79 ("scripts: kernel-doc: fix parsing function-like typedefs")
Signed-off-by: Sean Anderson <sean.anderson@linux.dev>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/e0abb103c73a96d76602d909f60ab8fd6e2fd0bd.1744106242.git.mchehab+huawei@kernel.org

show more ...

scripts/kernel-doc.py: Rename the kernel doc Re class to KernRe

Using just "Re" makes it harder to distinguish from the native
"re" class. So, let's rename it.

Signed-off-by: Mauro Carvalho Chehab

scripts/kernel-doc.py: Rename the kernel doc Re class to KernRe

Using just "Re" makes it harder to distinguish from the native
"re" class. So, let's rename it.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/4e095ecd5235a3e811ddcf5bad4cfb92f1da0a4a.1744106242.git.mchehab+huawei@kernel.org

show more ...

scripts/kernel_doc.py: better handle exported symbols

Change the logic which detects internal/external symbols in a way
that we can re-use it when calling via Sphinx extension.

While here, remove a

scripts/kernel_doc.py: better handle exported symbols

Change the logic which detects internal/external symbols in a way
that we can re-use it when calling via Sphinx extension.

While here, remove an unused self.config var and let it clearer
that self.config variables are read-only. This helps to allow
handling multiple times in parallel if ever needed.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/6a69ba8d2b7ee6a6427abb53e60d09bd4d3565ee.1744106242.git.mchehab+huawei@kernel.org

show more ...

scripts/kernel-doc.py: Properly handle Werror and exit codes

The original kernel-doc script has a logic to return warnings
as errors, and to report the number of warnings found, if in
verbose mode.

scripts/kernel-doc.py: Properly handle Werror and exit codes

The original kernel-doc script has a logic to return warnings
as errors, and to report the number of warnings found, if in
verbose mode.

Implement it to be fully compatible with the original script.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/de33b0cebd9fdf82d8b221bcfe41db7269286222.1744106242.git.mchehab+huawei@kernel.org

show more ...

scripts/lib/kdoc/kdoc_parser.py: remove a python 3.9 dependency

str.removesuffix() was added on Python 3.9, but rstrip()
actually does the same thing, as we just want to remove a single
character. I

scripts/lib/kdoc/kdoc_parser.py: remove a python 3.9 dependency

str.removesuffix() was added on Python 3.9, but rstrip()
actually does the same thing, as we just want to remove a single
character. It is also shorter.

So, use it.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/f64cc4adef107ada26da4bfb7e4b7002dd783173.1744106242.git.mchehab+huawei@kernel.org

show more ...

scripts/kernel-doc.py: move modulename to man class

Only man output requires a modulename. Move its definition
to the man class.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Sig

scripts/kernel-doc.py: move modulename to man class

Only man output requires a modulename. Move its definition
to the man class.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/583085e3885b0075d16ef9961b4f2ad870f30a55.1744106242.git.mchehab+huawei@kernel.org

show more ...

scripts/lib/kdoc/kdoc_parser.py: fix Python compat with < v3.13

- str.replace count was introduced only in Python 3.13;
- before Python 3.13, f-string dict arguments can't use the same
delimiter o

scripts/lib/kdoc/kdoc_parser.py: fix Python compat with < v3.13

- str.replace count was introduced only in Python 3.13;
- before Python 3.13, f-string dict arguments can't use the same
delimiter of the main string.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/e2b8e8361294558dae09236e4b8fbea5d86be5a3.1744106242.git.mchehab+huawei@kernel.org

show more ...

scripts/kernel-doc.py: adjust some coding style issues

Make pylint happier by adding some missing documentation and
addressing a couple of pylint warnings.

Signed-off-by: Mauro Carvalho Chehab <mch

scripts/kernel-doc.py: adjust some coding style issues

Make pylint happier by adding some missing documentation and
addressing a couple of pylint warnings.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/0f9d5473105e4c09c6c41e3db72cc63f1d4d55f9.1744106242.git.mchehab+huawei@kernel.org

show more ...

scripts/kernel-doc.py: postpone warnings to the output plugin

We don't want to have warnings displayed for symbols that
weren't output. So, postpone warnings print to the output
plugin, where symbol

scripts/kernel-doc.py: postpone warnings to the output plugin

We don't want to have warnings displayed for symbols that
weren't output. So, postpone warnings print to the output
plugin, where symbol output is validated.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/e6344711e390cf22af02a56bb5dd51ca67c0afb6.1744106242.git.mchehab+huawei@kernel.org

show more ...

scripts/kernel-doc.py: fix handling of doc output check

The filtering logic was seeking for the DOC name to check for
symbols, but such data is stored only inside a section. Add it
to the output_dec

scripts/kernel-doc.py: fix handling of doc output check

The filtering logic was seeking for the DOC name to check for
symbols, but such data is stored only inside a section. Add it
to the output_declaration, as it is quicker/easier to check
the declaration name than to check inside each section.

While here, make sure that the output for both ReST and man
after filtering will be similar to what kernel-doc Perl
version does.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/6d8b77af85295452c0191863ea1041f4195aeaaf.1744106242.git.mchehab+huawei@kernel.org

show more ...

scripts/kernel-doc.py: fix line number output

With the Pyhton version, the actual output happens after parsing,
from records stored at self.entries.

Ensure that line numbers will be properly stored

scripts/kernel-doc.py: fix line number output

With the Pyhton version, the actual output happens after parsing,
from records stored at self.entries.

Ensure that line numbers will be properly stored there and
that they'll produce the desired results at the ReST output.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/5182a531d14b5fe9e1fc5da5f9dae05d66852a60.1744106242.git.mchehab+huawei@kernel.org

show more ...

scripts/kernel-doc.py: move KernelDoc class to a separate file

In preparation for letting kerneldoc Sphinx extension to import
Python libraries, move regex ancillary classes to a separate
file.

Sig

scripts/kernel-doc.py: move KernelDoc class to a separate file

In preparation for letting kerneldoc Sphinx extension to import
Python libraries, move regex ancillary classes to a separate
file.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/c76df228504e711c6b4bcd23d5a0ea1fda678cda.1744106241.git.mchehab+huawei@kernel.org

show more ...