kernel/linux.git/Documentation/sphinx/automarkup.py, branch v7.1.6

docs: automarkup.py: Skip common English words as C identifiers

2026-01-27T17:35:57+00:00

The automarkup extension incorrectly recognizes common English words as C identifiers when they follow struct/union/enum/typedef keywords, causing normal text like "... (a simple) struct that" (in `workqueue.rst`) to be rendered as code blocks. This patch adds Skipidentifiers list to filter out these words. Signed-off-by: Yulong Han Signed-off-by: Jonathan Corbet Message-ID: <20260125124450.2005006-1-wheatfox17@icloud.com>

Documentation/sphinx: Fix typo in automarkup.py

2025-08-18T15:45:47+00:00

"whan" -> "when" Signed-off-by: Iris Shi <0.0@owo.li> Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/8e5ddb7d-8faf-314f-b1b1-2d15d6900862@owo.li

docs: sphinx: avoid using the deprecated node.set_class()

2025-06-21T19:18:03+00:00

Docutils emits a deprecation warning when the set_class() element method is used; that warning disappears into the ether, but it also causes a crash with docutils 0.19. Avoid the deprecated function and just append directly to the "classes" attribute like the documentation says instead. Reported-by: Akira Yokosawa Tested-by: Akira Yokosawa Closes: https://lore.kernel.org/de7bae91-3200-481f-9db2-c0dc382c91dd@gmail.com/ Fixes: d6d1df92c25f ("docs: automarkup: Mark up undocumented entities too") Signed-off-by: Jonathan Corbet

docs: automarkup: Mark up undocumented entities too

2025-06-09T20:43:09+00:00

The automarkup code generates markup and a cross-reference link for functions, structs, etc. for which it finds kerneldoc documentation. Undocumented entities are left untouched; that creates an inconsistent reading experience and has caused some writers to go to extra measures to cause the markup to happen. Mark up detected C entities regardless of whether they are documented. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet

docs: automarkup: Remove some Sphinx 2 holdovers

2025-06-09T20:42:38+00:00

Remove a few declarations that are no longer doing anything now that we have left Sphinx 2 behind. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet

docs: automarkup: Move common logic to add and resolve xref to helper

2025-04-14T16:04:07+00:00

Several of the markup functions contain the same code, calling into sphinx's pending_xref and resolve_xref functions to add and resolve a cross-reference, with only a few of the parameters changed (domain, reference type, markup content). Move this logic to its own function and reuse it in the markup functions. No functional change. Signed-off-by: Nícolas F. R. A. Prado Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250408-automarkup-resolve-xref-helper-v2-1-e0a9b8fc7fdd@collabora.com

docs: automarkup: drop legacy support

2025-02-18T20:42:46+00:00

Python 2 is already EOL for quite some time. Drop support for it. Also, the minimal Sphinx version is now 3.4.3. So, we can drop support for Sphinx < 3. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/5cb57d158e42957d4bff06db38be141d849ac13b.1739254867.git.mchehab+huawei@kernel.org

docs: media: Allow creating cross-references for RC ABI

2025-02-18T20:42:46+00:00

Now that Documentation/ABI is processed by automarkup, let it generate cross-references for RC sysfs devnodes. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/7c2f9a9970a15df8b5e3a6ecd21bcedcc8881ce1.1739254867.git.mchehab+huawei@kernel.org

docs: sphinx/kernel_abi: avoid warnings during Sphinx module init

2025-02-10T18:19:57+00:00

Sphinx logging system doesn't like warnings during module load, as it understands that such logs are produced at the wrong time: WARNING: while setting up extension automarkup: /sys/devices/system/cpu/cpuX/topology/physical_package_id is defined 2 times: /new_devel/v4l/docs/Documentation/ABI/stable/sysfs-devices-system-cpu:27; /new_devel/v4l/docs/Documentation/ABI/testing/sysfs-devices-system-cpu:70 WARNING: while setting up extension automarkup: /sys/devices/system/cpu/cpuX/topology/ppin is defined 2 times: /new_devel/v4l/docs/Documentation/ABI/stable/sysfs-devices-system-cpu:89; /new_devel/v4l/docs/Documentation/ABI/testing/sysfs-devices-system-cpu:70 So, use a function to allocate/process ABI files and use it to be called at kernel_abi.py, as automarkup also needs it to produce the right cross-references. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/b0e79dc60d556e3b39fa6774d3b7bf734b73f352.1739182025.git.mchehab+huawei@kernel.org

docs: sphinx/automarkup: add cross-references for ABI

2025-02-10T18:19:57+00:00

Now that all ABI files are handled together, we can add a feature at automarkup for it to generate cross-references for ABI symbols. The cross-reference logic can produce references for all existing files, except for README (as this is not parsed). For symbols, they need to be an exact match of what it is described at the docs, which is not always true due to wildcards. If symbols at /sys /proc and /config are identical, a cross-reference will be used. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/0b97a51b68b1c20127ad4a6a55658557fe0848d0.1739182025.git.mchehab+huawei@kernel.org