summaryrefslogtreecommitdiff
path: root/Documentation/sphinx/maintainers_include.py
AgeCommit message (Collapse)Author
2026-07-16docs: maintainers_include: fix entry namesMauro Carvalho Chehab
Right now, it is printing duplicated values as profile entries, as it is not properly handling subsystem name. Fix it. Reported-by: Manuel Ebner <manuelebner@mailbox.org> Closes: https://lore.kernel.org/linux-doc/98a558a87a07ab641f47c66c372ee7ed0735f4f5.camel@mailbox.org/ Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <bb00e9ba66f2d95306e7ca88fdf0f39fcc570cff.1783884625.git.mchehab+huawei@kernel.org>
2026-05-25docs: maintainers_include: keep the last entry at the endMauro Carvalho Chehab
The last maintainer's entry ("THE REST") is meant to be at the end. Ensure that. While here, use a case-insensitive sort to avoid placing "iSCSI" near the end. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <b4f45565eff4ba6f01e84a6877813038a23ba83b.1778952682.git.mchehab+huawei@kernel.org>
2026-05-25docs: maintainers_include: restore compatibility with Python 3.6Mauro Carvalho Chehab
glob root_dir parameter requires Python 3.10, which is more than our current Python minimal requirement. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <930036c189414f3f7096c22269687489f8566dd9.1778952682.git.mchehab+huawei@kernel.org>
2026-05-15docs: maintainers_include: better handle doc wildcardsMauro Carvalho Chehab
As warned by sashiko-bot, the new logic doesn't handle wildcards on Documentation/. Change the logic to properly handle it, cleaning up the code to remove some code duplication. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <eb575072d60c20243afee6f94ef71427ef7b2e79.1778309595.git.mchehab+huawei@kernel.org>
2026-05-15docs: maintainers_include: better handle directoriesMauro Carvalho Chehab
The TOC tree needs to use paths relative to the document containing the maintainers-profile-toc directive. Fix it. While here, address a warning from sashiko-bot, which points that using partition can be problematic if the root Linux path ends being something like: foo/Documentation/linux/ causing the documentation dir to be at: foo/Documentation/linux/Documentation Very unlikely, but fixing it is trivial: just use regex to pick the last one. Notice that I dropped the comment about using os.fspath() as the logic already uses os.path.abspath() which should work equally well. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <2b07e12eaa07bf81824ad427335783b170e01dba.1778309595.git.mchehab+huawei@kernel.org>
2026-05-15docs: maintainers_include: don't ignore invalid profile entriesMauro Carvalho Chehab
Currently, there is a "P" entry for Rust pin-init that is neither a valid ReST file inside Documentation nor an URL. A proper fix is to either convert/move the file or point to a URL. Yet, the parser should be able to pick what's there and show on its output. Add a logic to produce a warning when this happens. Message-ID: <63228e005fcf3dc4583cee06905341e8bce84181.1777987027.git.mchehab+huawei@kernel.org> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <98915f35442fa12c6d59611083aea3adbf8c6aff.1778309595.git.mchehab+huawei@kernel.org>
2026-05-15docs: maintainers_include: add a filtering javascriptMauro Carvalho Chehab
The maintainers table is big. Add a javascript to allow filtering it. Such script is only added at the page which contains the maintainers-include tag. I opted to keep the search case-sensitive, as, this way, upper case searches at subsystem. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Message-ID: <c435ef150f5d6ed16570969f43d92ba6fb857842.1777987027.git.mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <6f87c233351595358fddba11d42171be464f0a65.1778309595.git.mchehab+huawei@kernel.org>
2026-05-15docs: maintainers_include: properly handle file patternsMauro Carvalho Chehab
handling asterisks inside file patterns atdescription part is problematic, as ReST has special meaning for them. Due to that, convert such patterns to literal strings. Reported-by: Matteo Croce <teknoraver@meta.com> Fixes: 420849332f9f ("get_maintainer: add ** glob pattern support") Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Message-ID: <89127706fb3493d00ecb21e528c8a27081e5ed40.1777987027.git.mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <abd5112fea4dd480f5e72ba46fe60c2463862829.1778309595.git.mchehab+huawei@kernel.org>
2026-05-15docs: maintainers_include: store maintainers entries on a dictMauro Carvalho Chehab
Instead of creating just a big output data, store entries inside a dictionary. Doing that simplifies the parser a little bit and make the code clearer. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Message-ID: <4ad88179e03436984f29780ae380d50591f86c67.1777987027.git.mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <f7d1a206475ee54f757b2642882013097cb5453a.1778309595.git.mchehab+huawei@kernel.org>
2026-05-15docs: maintainers_include: do some coding style cleanupsMauro Carvalho Chehab
Minor coding style adjustments to use the style most python doc scripts are following. No functional changes. Assisted-by: pylint, black Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Message-ID: <460aabd0518f080b34e12fdc0beb7ec7685d5866.1777987027.git.mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <e041be77fcda3f1a54fdb428b3f8703bbce5d6ff.1778309595.git.mchehab+huawei@kernel.org>
2026-05-15docs: maintainers_include: clean most SPHINXDIRS=process warningsMauro Carvalho Chehab
building docs with SPHINXDIRS=process is too noisy, as it generates lots of undefined refs. Fixing it is easy: just let linkify generate html URLs for the broken links when SPHINXDIRS is used. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Message-ID: <b57d83081c28aa52683b403f8836d098fcdd8530.1777987027.git.mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <567200712771590d08e4da096b4def92bf729ffe.1778309595.git.mchehab+huawei@kernel.org>
2026-05-15docs: maintainers_include: cleanup the codeMauro Carvalho Chehab
Simplify the logic without affecting the output result. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Message-ID: <24a83995778de8710cac40a3089c2f2fe5c38dbd.1777987027.git.mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <5f48bf411925e923d206239a4de0a3e34592de88.1778309595.git.mchehab+huawei@kernel.org>
2026-05-15docs: maintainers_include: split state machine on multiple funcsMauro Carvalho Chehab
Instead of one big __init__ code, split the MaintainersParser code in a way that the state machine remains on __init__, but the actual parser for descriptions and subsystems are moved to separate functions. To make parser easier, instead storing parsed results on a list, place them directly on a string. That granted 15% of performance increase(*) with Python 3.14 and made the logic simpler. (*) measured by creating a new directory under Documentation/, and placing justmaintainers.rst and an index file there, building it via sphinx-build-wrapper. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Message-ID: <0b72530cf496ce5e2987ca784058a50f4dc814d2.1777987027.git.mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <26376e92a5e31e5d285b8676ed443a247b42e4c5.1778309595.git.mchehab+huawei@kernel.org>
2026-05-15docs: maintainers_include: keep hidden TOC sortedMauro Carvalho Chehab
There's no practical difference on keeping it sorted, but it helps a lot when checking for differences after patches to the tool. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Message-ID: <e6b302f2826e6a5c0124bb33cc517e8b5888252b.1777987027.git.mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <2742993764f2193101536a1cea40e034d75e0539.1778309595.git.mchehab+huawei@kernel.org>
2026-05-03docs: maintainers_include: parse MAINTAINERS just onceMauro Carvalho Chehab
Change the logic to parse MAINTAINERS file content just once, while still allowing using it multiple times. Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Tested-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <8060589074f54a276e563db8cad124d3f88346c7.1777295258.git.mchehab+huawei@kernel.org>
2026-05-03docs: maintainers_include: fix support for O=dirMauro Carvalho Chehab
os.path.relpath() will do the wrong thing with O=dir, as the build system uses "cd <dir>" internally. Solve it by using app.srcdir, which, on normal cases, point to Documentation/, or, when SPHINXDIRS=process, it will be set with Documentation/process. While here, remove a dead code while writing maintainer profiles, as now all entries should have both profile and entry. Reported-by: Randy Dunlap <rdunlap@infradead.org> Closes: https://lore.kernel.org/linux-doc/88335220-3527-4b1f-9500-417f7ebb7a02@infradead.org/T/#m6854cbd8d30e2c5d3e8c4173bae1c3d6922ff970 Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Tested-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <193792d73d08d9f8b9faa8b3df8a1a7439344a28.1777295258.git.mchehab+huawei@kernel.org>
2026-05-03docs: maintainers_include: improve its outputMauro Carvalho Chehab
There are three "types" of profiles: 1. Profiles already included inside subsystem-specific documentation. This is the most common case; 2. Profiles that are hosted externally; 3. Profiles that are at the same location as maintainer-handbooks.rst. For (3), we need to create a TOC, as they don't exist elsewhere. Change the logic to create TOC just for (3), prepending the content of maintainer-handbooks with a sorted entry of all types, before the TOC. With such change, we can have an unique sorted list of profiles, having the subsystem names used there listed. Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Tested-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <10d06a3f530e07ad981aba93617a9a7f4d63c408.1777295258.git.mchehab+huawei@kernel.org>
2026-05-03docs: maintainers_include: Only show main entry for profilesMauro Carvalho Chehab
Instead of showing as a "Contents:" with 2 identation levels, drop its title and show profiles as a list of entries. Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Tested-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <387b42c523e7b9f33e61cdff6fadb1df265cf71d.1777295258.git.mchehab+huawei@kernel.org>
2026-05-03docs: maintainers_include: preserve names for files under process/Mauro Carvalho Chehab
When a maintainer's profile is stored outside process, they're already included on some other book and the name of the filesystem may not be there. That's why the logic picks the name from the subsystem's name. However, files directly placed together with maintainers-handbooks.rst (e.g. under Documentation/process/) is a different history: those aren't placed anywhere, so we can keep using their own names, letting Sphinx do his thing. Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Tested-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <46961bc932be804cec19f06d202c23423d4aa12a.1777295258.git.mchehab+huawei@kernel.org>
2026-05-03docs: maintainers_include: add external profile URLsMauro Carvalho Chehab
Some subsystem profiles are maintained elsewhere. Add them to the output. Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Tested-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <b80639a38abdc934589e88bc9fc3029ad5c20bfe.1777295258.git.mchehab+huawei@kernel.org>
2026-05-03docs: maintainers_include: use a better title for profilesMauro Carvalho Chehab
As we're picking the name of the subsystem from MAINTAINERS, also use its subsystem name for the titles. Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Tested-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <8ce9c77c4d8c98e6bad37d838b0e359c8416040c.1777295258.git.mchehab+huawei@kernel.org>
2026-05-03docs: maintainers_include: auto-generate maintainer profile TOCMauro Carvalho Chehab
Add a feature to allow auto-generating media entry profiles from the corresponding field inside MAINTAINERS file(s). Suggested-by: Dan Williams <djbw@kernel.org> Closes: https://lore.kernel.org/linux-doc/69dd6299440be_147c801005b@djbw-dev.notmuch/ Acked-by: Dan Williams <djbw@kernel.org> Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Tested-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Message-ID: <4e9512a3d05942c98361d06d60a118d7c78762b6.1776176108.git.mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <eac5fb166bcbf0f267e762d72b150bbf248ff057.1777295258.git.mchehab+huawei@kernel.org>
2025-09-15docs: kdoc: handle the obsolescensce of docutils.ErrorString()Jonathan Corbet
The ErrorString() and SafeString() docutils functions were helpers meant to ease the handling of encodings during the Python 3 transition. There is no real need for them after Python 3.6, and docutils 0.22 removes them, breaking the docs build Handle this by just injecting our own one-liner version of ErrorString(), and removing the sole SafeString() call entirely. Reported-by: Zhixu Liu <zhixu.liu@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <87ldmnv2pi.fsf@trenco.lwn.net>
2025-02-13docs: extensions: don't use utf-8 syntax for descriptionsMauro Carvalho Chehab
None of the descriptions at the Sphinx extensions are using non-ascii characters, so no need to place them under u""" notation. Also, according with: https://docs.python.org/3/deprecations/pending-removal-in-3.16.html the 'u' format code is scheduled to be removed in Python 3.16. So, let's just use """. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Reviewed-by: Kees Cook <kees@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/8a42f6be53464af4b866492a7e9ddf29c0429997.1739254187.git.mchehab+huawei@kernel.org
2023-09-12Documentation/sphinx: fix Python string escapesBenjamin Gray
Python 3.6 introduced a DeprecationWarning for invalid escape sequences. This is upgraded to a SyntaxWarning in Python 3.12, and will eventually be a syntax error. Fix these now to get ahead of it before it's an error. Signed-off-by: Benjamin Gray <bgray@linux.ibm.com> Message-ID: <20230912060801.95533-3-bgray@linux.ibm.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-02-01Docs: drop Python 2 supportJonathan Corbet
The kernel build system as a whole is dropping support for Python 2, so we should do the same. The effects are rather small, especially considering that much of the deleted code was not doing anything under any version of Python anyway. Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2019-10-02doc-rst: Programmatically render MAINTAINERS into ReSTKees Cook
In order to have the MAINTAINERS file visible in the rendered ReST output, this makes some small changes to the existing MAINTAINERS file to allow for better machine processing, and adds a new Sphinx directive "maintainers-include" to perform the rendering. Features include: - Per-subsystem reference links: subsystem maintainer entries can be trivially linked to both internally and external. For example: https://www.kernel.org/doc/html/latest/process/maintainers.html#secure-computing - Internally referenced .rst files are linked so they can be followed when browsing the resulting rendering. This allows, for example, the future addition of maintainer profiles to be automatically linked. - Field name expansion: instead of the short fields (e.g. "M", "F", "K"), use the indicated inline "full names" for the fields (which are marked with "*"s in MAINTAINERS) so that a rendered subsystem entry is more human readable. Email lists are additionally comma-separated. For example: SECURE COMPUTING Mail: Kees Cook <keescook@chromium.org> Reviewer: Andy Lutomirski <luto@amacapital.net>, Will Drewry <wad@chromium.org> SCM: git git://git.kernel.org/pub/scm/linux/kernel/git/kees/linux.git seccomp Status: Supported Files: kernel/seccomp.c include/uapi/linux/seccomp.h include/linux/seccomp.h tools/testing/selftests/seccomp/* tools/testing/selftests/kselftest_harness.h userspace-api/seccomp_filter Content regex: \bsecure_computing \bTIF_SECCOMP\b Signed-off-by: Kees Cook <keescook@chromium.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>