summaryrefslogtreecommitdiff
path: root/Documentation/sphinx
AgeCommit message (Collapse)Author
2025-08-29docs: kernel_include.py: add support to generate a TOC tableMauro Carvalho Chehab
When generate-cross-refs is used, instead of just implementing the default of generating a literal block, we can also generate a ReST file as a TOC. The advantage is that, by being a ReST file, missing references will point to the place inside the header file that has the broken link. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/c0d32cd1ef94017e05984b0a38bd2516f7db21e2.1755872208.git.mchehab+huawei@kernel.org
2025-08-29docs: kernel_include.py: move code and literal functionsMauro Carvalho Chehab
Simplify run() even more by moving the code which handles with code and literal blocks to their own functions. No functional changes. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/78d08dfa3f08adabc30bf93b8a1cde4e19b7bd41.1755872208.git.mchehab+huawei@kernel.org
2025-08-29docs: kernel_include.py: remove range restriction for gen docsMauro Carvalho Chehab
Originally, parse-readers were generating an output where the first two lines were setting a literal block. The script now gets only the actual parsed data without that, so it is now safe to allow start-line and end-line parameters to be handled. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/5dff693860a6a3faade15c24abdc380f09db468d.1755872208.git.mchehab+huawei@kernel.org
2025-08-29docs: kernel_include.py: move range logic to a separate functionMauro Carvalho Chehab
Cleanup run() function by moving the range logic to a separate function. Here, I ended checking the current Sphinx implementation, as it has some extra logic for the range check. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/12fa2204a9e7e309ae4b8694a37ebad9327ca634.1755872208.git.mchehab+huawei@kernel.org
2025-08-29docs: kernel_include.py: move rawtext logic to separate functionsMauro Carvalho Chehab
The run function is too complex. merge run() and _run() into a single function and move the read logic to separate functions. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/04776a94c85b6c931c198a149f08b299c9f571a3.1755872208.git.mchehab+huawei@kernel.org
2025-08-29docs: kernel_include.py: generate warnings for broken refsMauro Carvalho Chehab
In the past, Sphinx used to warn about broken references. That's basically the rationale for adding media uAPI files: to get warnings about missed symbols. This is not true anymore. So, we need to explicitly check them after doctree-resolved event. While here, move setup() to the end, to make it closer to what we do on other extensions. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/73be9a198746421687e2eee916ccf8bf67980b7d.1755872208.git.mchehab+huawei@kernel.org
2025-08-29docs: kernel_include.py: allow cross-reference generationMauro Carvalho Chehab
kernel_include extension was originally designed to be used by the media comprehensive uAPI documentation, where, instead of simpler kernel-doc markups, the uAPI documentation is enriched with a larger text, with images, complex tables, graphs, etc. There, we wanted to include the much simpler yet documented .h file. This extension is needed to include files from other parts of the Kernel tree outside Documentation, because the original Sphinx include tag doesn't allow going outside of the directory passed via sphinx-build command line. Yet, the cross-references themselves to the full documentation were using a perl script to create cross-references against the comprehensive documentation. As the perl script is now converted to Phython and there is a Python class producing an include-compatible output with cross references, add two optional arguments to kernel_include.py: 1. :generate-cross-refs: If present, instead of reading the file, it calls ParseDataStructs() class, which converts C data structures into cross-references to be linked to ReST files containing a more comprehensive documentation; Don't use it together with :start-line: and/or :end-line:, as filtering input file line range is currently not supported. 2. :exception-file: Used together with :generate-cross-refs:. Points to a file containing rules to ignore C data structs or to use a different reference name, optionally using a different reference type. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/efc39c8e54a2056ae2fdb94d5006fcb19e227198.1755872208.git.mchehab+huawei@kernel.org
2025-08-29docs: kernel_include.py: Update its coding styleMauro Carvalho Chehab
With the help of tools like black, pylint, autopep8 and flake, improve the code style in preparation for further changes. No functional changes. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/f64c3af47fdfd632bb5f8eb88e3c7d94b0b84a66.1755872208.git.mchehab+huawei@kernel.org
2025-08-29tools: docs: parse-headers.py: move it from sphinx dirMauro Carvalho Chehab
As suggested by Jon, we should start having a tools/docs directory, instead of placing everything under scripts. In the specific case of parse-headers.py, the previous location is where we're placing Sphinx extensions, which is not the right place for execs. Move it to tools/docs/parse-headers.py. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/0f5ac2d704cffe9834e589b39549d2393e1237ef.1755872208.git.mchehab+huawei@kernel.org
2025-08-29docs: parse-headers.py: simplify the rules for hashesMauro Carvalho Chehab
Normal :ref domain accept either hashes or underscores, but c-domain ones don't. Fix it and remove unneeded places where we opt to disable underscore transformation. Ideally, we should have a rule about the default, or change the way media docs have their references. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/0c011090272f7a1068545409222f970ddb1ed431.1755872208.git.mchehab+huawei@kernel.org
2025-08-29docs: parse-headers.py: better handle @var argumentsMauro Carvalho Chehab
The kernel-doc markups inside headers may contain @var markups. With the current rule, this would be converted into: \* @:c:type:`DMX_BUFFER_FLAG_DISCONTINUITY_INDICATOR <dmx_buffer_flags>`\: Fix it adding a non-printed space if 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/8d06bb713d6ec8de65179dd93defe479715409b6.1755872208.git.mchehab+huawei@kernel.org
2025-08-29docs: parse-headers.py: improve --help logicMauro Carvalho Chehab
When printing --help, we'd like the name of the files from __doc__ to match the displayed positional arguments at both usage and argument description lines. Use a custom formatter class to convert ``foo`` into ANSI SGR code to bold the argument, if is TTY, and adjust the help text to match the argument names. Here on Plasma, that makes it display it colored, wich is really cool. Yet, I opted for SGR, as the best is to follow the terminal color schema for bold. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/2c1e61d1fb1b2a2838b443beee89c1528831997f.1755872208.git.mchehab+huawei@kernel.org
2025-08-29docs: parse-headers.py: convert parse-headers.plMauro Carvalho Chehab
When the Kernel started to use Sphinx, we had to come up with a solution to parse media headers. On that time, we didn't have much experience with Sphinx extensions. So, we came up with our own script-based solution that were basically implementing a set of rules we used to have at the Makefile. Convert it to Python, keeping it bug-compatible with the original script. While here, try to better document 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/ae5cfa8dff37e280cc9493fc95a51cd0cc0ba127.1755872208.git.mchehab+huawei@kernel.org
2025-08-29docs: parse-headers.pl: improve its debug output formatMauro Carvalho Chehab
Change the --debug logic to help comparing its results with a new python 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/1064011717951eac257889a3032303c9d4440711.1755872208.git.mchehab+huawei@kernel.org
2025-08-18Documentation/sphinx: Fix typo in automarkup.pyIris Shi
"whan" -> "when" Signed-off-by: Iris Shi <0.0@owo.li> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/8e5ddb7d-8faf-314f-b1b1-2d15d6900862@owo.li
2025-08-12sphinx: parser_yaml.py: fix line numbers informationMauro Carvalho Chehab
As reported by Donald, this code: rst_parser = RSTParser() rst_parser.parse('\n'.join(result), document) breaks line parsing. As an alternative, I tested a variant of it: rst_parser.parse(result, document) but still line number was not preserved. As Donald noted, standard Parser classes don't have a direct mechanism to preserve line numbers from ViewList(). So, instead, let's use a mechanism similar to what we do already at kerneldoc.py: call the statemachine mechanism directly there. I double-checked when states and statemachine were introduced: both were back in 2002. I also tested doc build with docutils 0.16 and 0.21.2. It worked with both, so it seems to be stable enough for our needs. Reported-by: Donald Hunter <donald.hunter@gmail.com> Closes: https://lore.kernel.org/linux-doc/m24ivk78ng.fsf@gmail.com/T/#u Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
2025-08-12docs: parser_yaml.py: fix backward compatibility with old docutilsMauro Carvalho Chehab
As reported by Akira, older docutils versions are not compatible with the way some Sphinx versions send tab_width. Add a code to address it. Reported-by: Akira Yokosawa <akiyks@gmail.com> Closes: https://lore.kernel.org/linux-doc/598b2cb7-2fd7-4388-96ba-2ddf0ab55d2a@gmail.com/ Tested-by: Akira Yokosawa <akiyks@gmail.com> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
2025-08-12docs: parser_yaml.py: add support for line numbers from the parserMauro Carvalho Chehab
Instead of printing line numbers from the temp converted ReST file, get them from the original source. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
2025-08-12docs: sphinx: add a parser for yaml files for Netlink specsMauro Carvalho Chehab
Add a simple sphinx.Parser to handle yaml files and add the the code to handle Netlink specs. All other yaml files are ignored. The code was written in a way that parsing yaml for different subsystems and even for different parts of Netlink are easy. All it takes to have a different parser is to add an import line similar to: from doc_generator import YnlDocGenerator adding the corresponding parser somewhere at the extension: netlink_parser = YnlDocGenerator() And then add a logic inside parse() to handle different doc outputs, depending on the file location, similar to: if "/netlink/specs/" in fname: msg = self.netlink_parser.parse_yaml_file(fname) Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Reviewed-by: Donald Hunter <donald.hunter@gmail.com>
2025-07-24sphinx: kernel_abi: fix performance regression with O=<dir>Mauro Carvalho Chehab
The logic there which adds a dependency note to Sphinx cache is not taking into account that the build dir may not be the source dir. This causes a performance regression: $ time make O=/tmp/foo SPHINXDIRS=admin-guide htmldocs [OUTDATED] Added: set() Changed: {'abi-obsolete', 'abi-removed', 'abi-stable-files', 'abi-obsolete-files', 'abi-stable', 'abi', 'abi-removed-files', 'abi-testing-files', 'abi-testing', 'gpio/index', 'gpio/obsolete'} Removed: set() All docs count: 385 Found docs count: 385 real 0m11,324s user 0m15,783s sys 0m1,164s To get the root cause of the problem (ABI files reported as changed), I used this changeset: diff --git a/Documentation/conf.py b/Documentation/conf.py index e8766e689c1b..ab486623bd8b 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -571,3 +571,16 @@ def setup(app): """Patterns need to be updated at init time on older Sphinx versions""" app.connect('config-inited', update_patterns) + app.connect('env-get-outdated', on_outdated) + +def on_outdated(app, env, added, changed, removed): + """Track cache outdated due to added/changed/removed files""" + print("\n[OUTDATED]") + print(f"Added: {added}") + print(f"Changed: {changed}") + print(f"Removed: {removed}") + print(f"All docs count: {len(env.all_docs)}") + print(f"Found docs count: {len(env.found_docs)}") + + # Just return what we have + return added | changed | removed Reported-by: Akira Yokosawa <akiyks@gmail.com> Closes: https://lore.kernel.org/linux-doc/c174f7c5-ec21-4eae-b1c3-f643cca90d9d@gmail.com/ Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Tested-by: Akira Yokosawa <akiyks@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/e25673d87357457bc54ee863e97ff8f75956580d.1752752211.git.mchehab+huawei@kernel.org
2025-07-08docs: kdoc: Remove a Python 2 commentJonathan Corbet
We no longer support Python 2 in the docs build chain at all, so we certainly do not need to admonish folks to keep this file working with it. Cc: Jani Nikula <jani.nikula@intel.com> Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Acked-by: Jani Nikula <jani.nikula@intel.com> Tested-by: Akira Yokosawa <akiyks@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20250703184403.274408-7-corbet@lwn.net
2025-06-25docs: sphinx: add missing SPDX tagsMauro Carvalho Chehab
Several Sphinx extensions and tools are missing SPDX tags. Add them. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/1a62226c5fe524eb87bdb80b33bc7ec880a68880.1750585188.git.mchehab+huawei@kernel.org
2025-06-25docs: sphinx: add a file with the requirements for lowest versionMauro Carvalho Chehab
Those days, it is hard to install a virtual env that would build docs with Sphinx 3.4.3, as even python 3.13 is not compatible anymore with it. /usr/bin/python3.9 -m venv sphinx_3.4.3 . sphinx_3.4.3/bin/activate pip install -r Documentation/sphinx/min_requirements.txt Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/e38a44ee64ebfa37eac5f64e47af51c7ac051d5a.1750571906.git.mchehab+huawei@kernel.org
2025-06-21docs: sphinx: avoid using the deprecated node.set_class()Jonathan Corbet
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 <akiyks@gmail.com> Tested-by: Akira Yokosawa <akiyks@gmail.com> 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 <corbet@lwn.net>
2025-06-09docs: automarkup: Mark up undocumented entities tooJonathan Corbet
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 <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2025-06-09docs: automarkup: Remove some Sphinx 2 holdoversJonathan Corbet
Remove a few declarations that are no longer doing anything now that we have left Sphinx 2 behind. Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2025-05-21docs: kerneldoc.py: simplify exception handling logicMauro Carvalho Chehab
Get rid of logger.verbose() which is causing the logger to not work. Also, instead of having try/except everywhere, place them on a common place. While here, get rid of some bogus logs. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Acked-by: Akira Yokosawa <akiyks@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <a2cc32d5d519ed343158a915c39e8dc536a8ddb7.1747817887.git.mchehab+huawei@kernel.org>
2025-04-28docs: Sphinx: kerneldoc: only initialize kernel-doc classes onceMauro Carvalho Chehab
Instead of re-creating the objects every time, initialize it just once. This allows caching previously parsed objects. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <b00788f26e161512858a6e01a673c34743c954df.1745564565.git.mchehab+huawei@kernel.org>
2025-04-21docs: sphinx: kerneldoc: Use python class if availableMauro Carvalho Chehab
Better integrate with the new kernel-doc tool by calling the Python classes directly if KERNELDOC=scripts/kernel-doc.py. This way, warnings won't be duplicated anymore, as files will be parsed only once. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/1556a6c005d8e0fafa951f74725e984e1c7459bf.1744685912.git.mchehab+huawei@kernel.org
2025-04-14docs: automarkup: Move common logic to add and resolve xref to helperNícolas F. R. A. Prado
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 <nfraprado@collabora.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20250408-automarkup-resolve-xref-helper-v2-1-e0a9b8fc7fdd@collabora.com
2025-04-09docs: sphinx: kerneldoc: ignore "\" characters from optionsMauro Carvalho Chehab
Documentation/driver-api/infiniband.rst has a kernel-doc tag with "\" characters at the end: .. kernel-doc:: drivers/infiniband/ulp/iser/iscsi_iser.c :functions: iscsi_iser_pdu_alloc iser_initialize_task_headers \ iscsi_iser_task_init iscsi_iser_mtask_xmit iscsi_iser_task_xmit \ iscsi_iser_cleanup_task iscsi_iser_check_protection \ iscsi_iser_conn_create iscsi_iser_conn_bind \ iscsi_iser_conn_start iscsi_iser_conn_stop \ iscsi_iser_session_destroy iscsi_iser_session_create \ iscsi_iser_set_param iscsi_iser_ep_connect iscsi_iser_ep_poll \ iscsi_iser_ep_disconnect This is not handled well, as the "\" strings will be just stored inside Sphinx options. While the actual problem deserves being fixed, better to relax the keneldoc.py extension to silently strip "\" from the end of strings, as otherwise this may cause troubles when preparing arguments to be executed by kernel-doc. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/4c652d6c57b20500c135b95294e554d9e9a97f42.1744106242.git.mchehab+huawei@kernel.org
2025-04-09docs: sphinx: kerneldoc: verbose kernel-doc command if V=1Mauro Carvalho Chehab
It is useful to know what kernel-doc command was used during document build time, as it allows one to check the output the same way as Sphinx extension 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/a2f01590814b111e138f278e8a721024fdf2d445.1744106242.git.mchehab+huawei@kernel.org
2025-02-18docs: automarkup: drop legacy supportMauro Carvalho Chehab
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 <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/5cb57d158e42957d4bff06db38be141d849ac13b.1739254867.git.mchehab+huawei@kernel.org
2025-02-18docs: media: Allow creating cross-references for RC ABIMauro Carvalho Chehab
Now that Documentation/ABI is processed by automarkup, let it generate cross-references for RC sysfs devnodes. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/7c2f9a9970a15df8b5e3a6ecd21bcedcc8881ce1.1739254867.git.mchehab+huawei@kernel.org
2025-02-13scripts/kernel-doc: drop Sphinx version checkMauro Carvalho Chehab
As the current minimal supported Sphinx version is 3.4.3, drop support for older versions. 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/0d002e7550476a68547ee53ad06cfd8fdcaf7c3a.1739254187.git.mchehab+huawei@kernel.org
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
2025-02-10docs: sphinx/kernel_abi: avoid warnings during Sphinx module initMauro Carvalho Chehab
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 <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/b0e79dc60d556e3b39fa6774d3b7bf734b73f352.1739182025.git.mchehab+huawei@kernel.org
2025-02-10docs: sphinx/automarkup: add cross-references for ABIMauro Carvalho Chehab
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 <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/0b97a51b68b1c20127ad4a6a55658557fe0848d0.1739182025.git.mchehab+huawei@kernel.org
2025-02-10docs: sphinx/kernel_abi: parse ABI files only onceMauro Carvalho Chehab
Right now, the logic parses ABI files on 4 steps, one for each directory. While this is fine in principle, by doing that, not all symbol cross-references will be created. Change the logic to do the parsing only once in order to get a global dictionary to be used when creating ABI cross-references. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/5205c53838b6ea25f4cdd4cc1e3d17c0141e75a6.1739182025.git.mchehab+huawei@kernel.org
2025-02-10docs: sphinx/kernel_abi: properly split linesMauro Carvalho Chehab
Sphinx doesn't like to have lines split with str.split("\n"). Instead, it uses its own splitter, with handles line breaks the way Spinx expects. Not using it cause issues at the output files. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/d4ad5b977799616544376210364d5cec686119ef.1739182025.git.mchehab+huawei@kernel.org
2025-02-10docs: sphinx/kernel_abi: reduce buffer usage for ABI messagesMauro Carvalho Chehab
Instead of producing a big message with all ABI contents and then parse as a whole, simplify the code by handling each ABI symbol in separate. As an additional benefit, there's no need to place file/line nubers inlined at the data and use a regex to convert them. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/15be22955e3c6df49d7256c8fd24f62b397ad0ff.1739182025.git.mchehab+huawei@kernel.org
2025-02-10docs: sphinx/kernel_abi: use AbiParser directlyMauro Carvalho Chehab
Instead of running get_abi.py script, import AbiParser class and handle messages directly there using an interactor. This shold save some memory, as there's no need to exec python inside the Sphinx python extension. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/8dbc244dcda97112c1b694e2512a5d600e62873b.1739182025.git.mchehab+huawei@kernel.org
2025-02-10docs: use get_abi.py for ABI generationMauro Carvalho Chehab
Use the new script instead of the old one when generating ABI docs. For now, execute it via exec. Future changes will better integrate it by using the class defined there directly. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/e7fcb121c0612c94f6f54f0d742cd3a26a46cd7d.1739182025.git.mchehab+huawei@kernel.org
2025-02-10docs: sphinx/kernel_abi: adjust coding styleMauro Carvalho Chehab
Make pylint and flake8 happier with this module's coding style Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/02a9ec0fab61e4c94b9c2ff555bc0e9d93f59100.1739182025.git.mchehab+huawei@kernel.org
2025-02-10docs: sphinx: remove kernellog.py fileMauro Carvalho Chehab
In the past, there was a need for a wrapper due to different Sphinx versions support (before Sphinx 1.6). This is long gone, and now it is just a wrapper. Get rig of it to simplify the code. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/48bf16f199250d7048ca164d1b90773861915157.1739182025.git.mchehab+huawei@kernel.org
2024-09-05docs: kerneldoc-preamble.sty: Suppress extra spaces in CJK literal blocksAkira Yokosawa
In zh_CN part of translations.pdf, there are several ASCII-art diagrams whose vertical lines look sometimes jagged. This is due to the interference between default settings of xeCJK and fancyvrb (employed in sphinxVerbatim env), where extra space is inserted between a latin char and a non-latin char when they are next to each other (i.e., no explicit white space). This issue can be suppressed by invoking \CJKsetecglue{} at the beginning of every sphinxVerbatim enviornment. \AtBeginEnvironment, provided by the etoolbox package, is useful in this case. Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20240905050941.31439-1-akiyks@gmail.com
2024-05-02docs: kernel_include.py: Cope with docutils 0.21Akira Yokosawa
Running "make htmldocs" on a newly installed Sphinx 7.3.7 ends up in a build error: Sphinx parallel build error: AttributeError: module 'docutils.nodes' has no attribute 'reprunicode' docutils 0.21 has removed nodes.reprunicode, quote from release note [1]: * Removed objects: docutils.nodes.reprunicode, docutils.nodes.ensure_str() Python 2 compatibility hacks Sphinx 7.3.0 supports docutils 0.21 [2]: kernel_include.py, whose origin is misc.py of docutils, uses reprunicode. Upstream docutils removed the offending line from the corresponding file (docutils/docutils/parsers/rst/directives/misc.py) in January 2022. Quoting the changelog [3]: Deprecate `nodes.reprunicode` and `nodes.ensure_str()`. Drop uses of the deprecated constructs (not required with Python 3). Do the same for kernel_include.py. Tested against: - Sphinx 2.4.5 (docutils 0.17.1) - Sphinx 3.4.3 (docutils 0.17.1) - Sphinx 5.3.0 (docutils 0.18.1) - Sphinx 6.2.1 (docutils 0.19) - Sphinx 7.2.6 (docutils 0.20.1) - Sphinx 7.3.7 (docutils 0.21.2) Link: http://www.docutils.org/RELEASE-NOTES.html#release-0-21-2024-04-09 [1] Link: https://www.sphinx-doc.org/en/master/changes.html#release-7-3-0-released-apr-16-2024 [2] Link: https://github.com/docutils/docutils/commit/c8471ce47a24 [3] Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Cc: stable@vger.kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/faf5fa45-2a9d-4573-9d2e-3930bdc1ed65@gmail.com
2024-04-10docs: Detect variable fonts and suggest denylisting themAkira Yokosawa
Fedora and openSUSE has started deploying "variable font" [1] format Noto CJK fonts [2, 3]. "CJK" here stands for "Chinese, Japanese, and Korean". Unfortunately, XeTeX/XeLaTeX doesn't understand those fonts for historical reasons and builds of translations.pdf end up in errors if such fonts are present on the build host. To help developers work around the issue, add a script to check the presence of "variable font" Noto CJK fonts and to emit suggestions. The script is invoked in the error path of "make pdfdocs" so that the suggestions are made only when a PDF build actually fails. The first suggestion is to denylist those "variable font" files by activating a per-user and command-local fontconfig setting. For further info and backgrounds, please refer to the header comment of scripts/check-variable-font.sh newly added in this commit. Link: [1] https://en.wikipedia.org/wiki/Variable_font Link: [2] https://fedoraproject.org/wiki/Changes/Noto_CJK_Variable_Fonts Link: [3] https://build.opensuse.org/request/show/1157217 Reported-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/8734tqsrt7.fsf@meer.lwn.net/ Reported-by: Иван Иванович <relect@bk.ru> Link: https://lore.kernel.org/linux-doc/1708585803.600323099@f111.i.mail.ru/ Cc: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20240406020416.25096-1-akiyks@gmail.com
2024-03-03docs: drop the version constraints for sphinx and dependenciesLukas Bulwahn
As discussed (see Links), there is some inertia to move to the recent Sphinx versions for the doc build environment. As first step, drop the version constraints and the related comments. As sphinx depends on jinja2, jinja2 is pulled in automatically. So drop that. Then, the sphinx-pre-install script will fail though with: Can't get default sphinx version from ./Documentation/sphinx/requirements.txt at ./scripts/sphinx-pre-install line 305. The script simply expects to parse a version constraint with Sphinx in the requirements.txt. That version is used in the script for suggesting the virtualenv directory name. To suggest a virtualenv directory name, when there is no version given in the requirements.txt, one could try to guess the version that would be downloaded with 'pip install -r Documentation/sphinx/requirements.txt'. However, there seems no simple way to get that version without actually setting up the venv and running pip. So, instead, name the directory with the fixed name 'sphinx_latest'. Finally update the Sphinx build documentation to reflect this directory name change. Link: https://lore.kernel.org/linux-doc/874jf4m384.fsf@meer.lwn.net/ Link: https://lore.kernel.org/linux-doc/20240226093854.47830-1-lukas.bulwahn@gmail.com/ Reviewed-by: Akira Yokosawa <akiyks@gmail.com> Tested-by: Vegard Nossum <vegard.nossum@oracle.com> Signed-off-by: Lukas Bulwahn <lukas.bulwahn@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <20240301141800.30218-1-lukas.bulwahn@gmail.com>
2024-03-03docs: kerneldoc-preamble.sty: Remove code for Sphinx <2.4Akira Yokosawa
Now that Sphinx 2.4.4 or better is required, get rid of \providecommand{}'s for compatibility with Sphinx 1.7.9. While at it, reword the comment on \sphinxtableofcontentshook for better description of why it needs to be emptied. Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <ed1ec6f2-0050-46f6-807d-8679f26427e9@gmail.com>
generated by cgit v1.2.3 (git 2.0.4) at 2026-08-06 01:33:48 +0000