aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/sphinx
Commit message (Collapse)AuthorAgeFilesLines
* sphinx: kernel_abi: fix performance regression with O=<dir>Mauro Carvalho Chehab2025-07-241-2/+4
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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 <[email protected]> Closes: https://lore.kernel.org/linux-doc/[email protected]/ Signed-off-by: Mauro Carvalho Chehab <[email protected]> Tested-by: Akira Yokosawa <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/e25673d87357457bc54ee863e97ff8f75956580d.1752752211.git.mchehab+huawei@kernel.org
* docs: kdoc: Remove a Python 2 commentJonathan Corbet2025-07-081-2/+0
| | | | | | | | | | | | 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 <[email protected]> Reviewed-by: Mauro Carvalho Chehab <[email protected]> Acked-by: Jani Nikula <[email protected]> Tested-by: Akira Yokosawa <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/[email protected]
* docs: sphinx: add missing SPDX tagsMauro Carvalho Chehab2025-06-259-1/+12
| | | | | | | | | Several Sphinx extensions and tools are missing SPDX tags. Add them. Signed-off-by: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/1a62226c5fe524eb87bdb80b33bc7ec880a68880.1750585188.git.mchehab+huawei@kernel.org
* docs: sphinx: add a file with the requirements for lowest versionMauro Carvalho Chehab2025-06-251-0/+10
| | | | | | | | | | | | | | 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 <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/e38a44ee64ebfa37eac5f64e47af51c7ac051d5a.1750571906.git.mchehab+huawei@kernel.org
* docs: sphinx: avoid using the deprecated node.set_class()Jonathan Corbet2025-06-211-1/+1
| | | | | | | | | | | | | | | 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 <[email protected]> Tested-by: Akira Yokosawa <[email protected]> Closes: https://lore.kernel.org/[email protected]/ Fixes: d6d1df92c25f ("docs: automarkup: Mark up undocumented entities too") Signed-off-by: Jonathan Corbet <[email protected]>
* docs: automarkup: Mark up undocumented entities tooJonathan Corbet2025-06-091-2/+7
| | | | | | | | | | | | | 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 <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]>
* docs: automarkup: Remove some Sphinx 2 holdoversJonathan Corbet2025-06-091-16/+2
| | | | | | | | Remove a few declarations that are no longer doing anything now that we have left Sphinx 2 behind. Reviewed-by: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]>
* docs: kerneldoc.py: simplify exception handling logicMauro Carvalho Chehab2025-05-211-63/+45
| | | | | | | | | | | | | | | 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 <[email protected]> Acked-by: Akira Yokosawa <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Message-ID: <a2cc32d5d519ed343158a915c39e8dc536a8ddb7.1747817887.git.mchehab+huawei@kernel.org>
* docs: Sphinx: kerneldoc: only initialize kernel-doc classes onceMauro Carvalho Chehab2025-04-281-12/+11
| | | | | | | | | | | Instead of re-creating the objects every time, initialize it just once. This allows caching previously parsed objects. Signed-off-by: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Message-ID: <b00788f26e161512858a6e01a673c34743c954df.1745564565.git.mchehab+huawei@kernel.org>
* docs: sphinx: kerneldoc: Use python class if availableMauro Carvalho Chehab2025-04-211-8/+130
| | | | | | | | | | | | 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 <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/1556a6c005d8e0fafa951f74725e984e1c7459bf.1744685912.git.mchehab+huawei@kernel.org
* docs: automarkup: Move common logic to add and resolve xref to helperNícolas F. R. A. Prado2025-04-141-73/+24
| | | | | | | | | | | | | | 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 <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/20250408-automarkup-resolve-xref-helper-v2-1-e0a9b8fc7fdd@collabora.com
* docs: sphinx: kerneldoc: ignore "\" characters from optionsMauro Carvalho Chehab2025-04-091-0/+12
| | | | | | | | | | | | | | | | | | | | | | | | | | | 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 <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/4c652d6c57b20500c135b95294e554d9e9a97f42.1744106242.git.mchehab+huawei@kernel.org
* docs: sphinx: kerneldoc: verbose kernel-doc command if V=1Mauro Carvalho Chehab2025-04-091-0/+34
| | | | | | | | | | 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 <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/a2f01590814b111e138f278e8a721024fdf2d445.1744106242.git.mchehab+huawei@kernel.org
* docs: automarkup: drop legacy supportMauro Carvalho Chehab2025-02-181-25/+7
| | | | | | | | | | | | 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 <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/5cb57d158e42957d4bff06db38be141d849ac13b.1739254867.git.mchehab+huawei@kernel.org
* docs: media: Allow creating cross-references for RC ABIMauro Carvalho Chehab2025-02-181-4/+13
| | | | | | | | | Now that Documentation/ABI is processed by automarkup, let it generate cross-references for RC sysfs devnodes. Signed-off-by: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/7c2f9a9970a15df8b5e3a6ecd21bcedcc8881ce1.1739254867.git.mchehab+huawei@kernel.org
* scripts/kernel-doc: drop Sphinx version checkMauro Carvalho Chehab2025-02-132-8/+0
| | | | | | | | | | As the current minimal supported Sphinx version is 3.4.3, drop support for older versions. Signed-off-by: Mauro Carvalho Chehab <[email protected]> Reviewed-by: Kees Cook <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/0d002e7550476a68547ee53ad06cfd8fdcaf7c3a.1739254187.git.mchehab+huawei@kernel.org
* docs: extensions: don't use utf-8 syntax for descriptionsMauro Carvalho Chehab2025-02-138-22/+22
| | | | | | | | | | | | | | | | | | 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 <[email protected]> Reviewed-by: Kees Cook <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/8a42f6be53464af4b866492a7e9ddf29c0429997.1739254187.git.mchehab+huawei@kernel.org
* docs: sphinx/kernel_abi: avoid warnings during Sphinx module initMauro Carvalho Chehab2025-02-102-5/+22
| | | | | | | | | | | | | | | | 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 <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/b0e79dc60d556e3b39fa6774d3b7bf734b73f352.1739182025.git.mchehab+huawei@kernel.org
* docs: sphinx/automarkup: add cross-references for ABIMauro Carvalho Chehab2025-02-101-0/+45
| | | | | | | | | | | | | | | | | | 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 <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/0b97a51b68b1c20127ad4a6a55658557fe0848d0.1739182025.git.mchehab+huawei@kernel.org
* docs: sphinx/kernel_abi: parse ABI files only onceMauro Carvalho Chehab2025-02-101-45/+58
| | | | | | | | | | | | | 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 <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/5205c53838b6ea25f4cdd4cc1e3d17c0141e75a6.1739182025.git.mchehab+huawei@kernel.org
* docs: sphinx/kernel_abi: properly split linesMauro Carvalho Chehab2025-02-101-2/+3
| | | | | | | | | | | 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 <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/d4ad5b977799616544376210364d5cec686119ef.1739182025.git.mchehab+huawei@kernel.org
* docs: sphinx/kernel_abi: reduce buffer usage for ABI messagesMauro Carvalho Chehab2025-02-101-37/+39
| | | | | | | | | | | | 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 <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/15be22955e3c6df49d7256c8fd24f62b397ad0ff.1739182025.git.mchehab+huawei@kernel.org
* docs: sphinx/kernel_abi: use AbiParser directlyMauro Carvalho Chehab2025-02-101-13/+16
| | | | | | | | | | | 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 <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/8dbc244dcda97112c1b694e2512a5d600e62873b.1739182025.git.mchehab+huawei@kernel.org
* docs: use get_abi.py for ABI generationMauro Carvalho Chehab2025-02-101-7/+3
| | | | | | | | | | | 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 <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/e7fcb121c0612c94f6f54f0d742cd3a26a46cd7d.1739182025.git.mchehab+huawei@kernel.org
* docs: sphinx/kernel_abi: adjust coding styleMauro Carvalho Chehab2025-02-101-13/+12
| | | | | | | | Make pylint and flake8 happier with this module's coding style Signed-off-by: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/02a9ec0fab61e4c94b9c2ff555bc0e9d93f59100.1739182025.git.mchehab+huawei@kernel.org
* docs: sphinx: remove kernellog.py fileMauro Carvalho Chehab2025-02-104-69/+53
| | | | | | | | | | | 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 <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/48bf16f199250d7048ca164d1b90773861915157.1739182025.git.mchehab+huawei@kernel.org
* docs: kerneldoc-preamble.sty: Suppress extra spaces in CJK literal blocksAkira Yokosawa2024-09-051-0/+2
| | | | | | | | | | | | | | | | | | | 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 <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/[email protected]
* docs: kernel_include.py: Cope with docutils 0.21Akira Yokosawa2024-05-021-1/+0
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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 <[email protected]> Cc: [email protected] Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/[email protected]
* docs: Detect variable fonts and suggest denylisting themAkira Yokosawa2024-04-101-4/+5
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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 <[email protected]> Link: https://lore.kernel.org/r/[email protected]/ Reported-by: Иван Иванович <[email protected]> Link: https://lore.kernel.org/linux-doc/[email protected]/ Cc: Randy Dunlap <[email protected]> Signed-off-by: Akira Yokosawa <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/[email protected]
* docs: drop the version constraints for sphinx and dependenciesLukas Bulwahn2024-03-031-5/+2
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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/[email protected]/ Link: https://lore.kernel.org/linux-doc/[email protected]/ Reviewed-by: Akira Yokosawa <[email protected]> Tested-by: Vegard Nossum <[email protected]> Signed-off-by: Lukas Bulwahn <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Message-ID: <[email protected]>
* docs: kerneldoc-preamble.sty: Remove code for Sphinx <2.4Akira Yokosawa2024-03-031-6/+1
| | | | | | | | | | | | 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 <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Message-ID: <[email protected]>
* Merge branch 'docs-fixes' into docs-mwJonathan Corbet2024-02-211-6/+4
|\ | | | | | | Bring in the build fixes so that we can successfully build PDFs again.
| * docs: translations: use attribute to store current languageVegard Nossum2024-02-211-6/+4
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Akira Yokosawa reported [1] that the "translations" extension we added in commit 7418ec5b151f ("docs: translations: add translations links when they exist") broke the build on Sphinx versions v6.1.3 through 7.1.2 (possibly others) with the following error: Exception occurred: File "/usr/lib/python3.12/site-packages/sphinx/util/nodes.py", line 624, in _copy_except__document newnode = self.__class__(rawsource=self.rawsource, **self.attributes) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ TypeError: LanguagesNode.__init__() missing 1 required positional argument: 'current_language' The full traceback has been saved in /tmp/sphinx-err-7xmwytuu.log, if you want to report the issue to the developers. Solve this problem by making 'current_language' a true element attribute of the LanguagesNode element, which is probably the more correct way to do it anyway. Tested on Sphinx 2.x, 3.x, 6.x, and 7.x. [1]: https://lore.kernel.org/all/[email protected]/ Fixes: 7418ec5b151f ("docs: translations: add translations links when they exist") Reported-by: Akira Yokosawa <[email protected]> Signed-off-by: Vegard Nossum <[email protected]> Closes: https://lore.kernel.org/all/[email protected]/ Tested-by: Akira Yokosawa <[email protected]> # Sphinx 4.3.2, 5.3.0 and 6.2.1 Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/[email protected]
| * docs: kernel_feat.py: fix build error for missing filesVegard Nossum2024-02-081-1/+1
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | If the directory passed to the '.. kernel-feat::' directive does not exist or the get_feat.pl script does not find any files to extract features from, Sphinx will report the following error: Sphinx parallel build error: UnboundLocalError: local variable 'fname' referenced before assignment make[2]: *** [Documentation/Makefile:102: htmldocs] Error 2 This is due to how I changed the script in c48a7c44a1d0 ("docs: kernel_feat.py: fix potential command injection"). Before that, the filename passed along to self.nestedParse() in this case was weirdly just the whole get_feat.pl invocation. We can fix it by doing what kernel_abi.py does -- just pass self.arguments[0] as 'fname'. Fixes: c48a7c44a1d0 ("docs: kernel_feat.py: fix potential command injection") Cc: Justin Forbes <[email protected]> Cc: Salvatore Bonaccorso <[email protected]> Cc: Jani Nikula <[email protected]> Cc: Mauro Carvalho Chehab <[email protected]> Cc: [email protected] Signed-off-by: Vegard Nossum <[email protected]> Link: https://lore.kernel.org/r/[email protected] Signed-off-by: Jonathan Corbet <[email protected]>
* | docs: kernel_feat.py: fix build error for missing filesVegard Nossum2024-02-211-1/+1
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | If the directory passed to the '.. kernel-feat::' directive does not exist or the get_feat.pl script does not find any files to extract features from, Sphinx will report the following error: Sphinx parallel build error: UnboundLocalError: local variable 'fname' referenced before assignment make[2]: *** [Documentation/Makefile:102: htmldocs] Error 2 This is due to how I changed the script in c48a7c44a1d0 ("docs: kernel_feat.py: fix potential command injection"). Before that, the filename passed along to self.nestedParse() in this case was weirdly just the whole get_feat.pl invocation. We can fix it by doing what kernel_abi.py does -- just pass self.arguments[0] as 'fname'. Fixes: c48a7c44a1d0 ("docs: kernel_feat.py: fix potential command injection") Cc: Justin Forbes <[email protected]> Cc: Salvatore Bonaccorso <[email protected]> Cc: Jani Nikula <[email protected]> Cc: Mauro Carvalho Chehab <[email protected]> Cc: [email protected] Signed-off-by: Vegard Nossum <[email protected]> Link: https://lore.kernel.org/r/[email protected] Signed-off-by: Jonathan Corbet <[email protected]>
* | doc: kerneldoc.py: fix indentationVegard Nossum2024-02-211-3/+3
|/ | | | | | | | | | | | | | kerneldoc.py is mostly indented with 4 spaces (like PEP8 suggests); replace the last remaining tabs for consistency. No functional change. Cc: Jani Nikula <[email protected]> Cc: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Vegard Nossum <[email protected]> Reviewed-by: Randy Dunlap <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/[email protected]
* docs/sphinx: Fix TOC scroll hack for the home pageGustavo Sousa2024-01-231-1/+3
| | | | | | | | | | | When on the documentation home page, there won't be any ".current" element since no entry from the TOC was selected yet. That results in a javascript error. Fix that by only trying to set the scrollTop if we have matches for current entries. Signed-off-by: Gustavo Sousa <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/[email protected]
* Merge tag 'docs-6.8-2' of git://git.lwn.net/linuxLinus Torvalds2024-01-172-44/+13
|\ | | | | | | | | | | | | | | | | | | | | | | | | Pull documentation fixes from Jonathan Corbet: "A handful of late-arriving documentation fixes" * tag 'docs-6.8-2' of git://git.lwn.net/linux: docs, kprobes: Add loongarch as supported architecture docs, kprobes: Update email address of Masami Hiramatsu docs: admin-guide: hw_random: update rng-tools website Documentation/core-api: fix spelling mistake in workqueue docs: kernel_feat.py: fix potential command injection Documentation: constrain alabaster package to older versions
| * docs: kernel_feat.py: fix potential command injectionVegard Nossum2024-01-111-44/+11
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | The kernel-feat directive passes its argument straight to the shell. This is unfortunate and unnecessary. Let's always use paths relative to $srctree/Documentation/ and use subprocess.check_call() instead of subprocess.Popen(shell=True). This also makes the code shorter. This is analogous to commit 3231dd586277 ("docs: kernel_abi.py: fix command injection") where we did exactly the same thing for kernel_abi.py, somehow I completely missed this one. Link: https://fosstodon.org/@jani/111676532203641247 Reported-by: Jani Nikula <[email protected]> Signed-off-by: Vegard Nossum <[email protected]> Cc: [email protected] Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/[email protected]
| * Documentation: constrain alabaster package to older versionsVegard Nossum2024-01-111-0/+2
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | The 'alabaster' theme dropped support for Sphinx < v3.4: 0.7.14 – 2024-01-08 * Dropped support for Python 3.8 and earlier. * Dropped support for Sphinx 3.3 and earlier. [...] (Source: https://alabaster.readthedocs.io/en/latest/changelog.html) This manifests as an error when running 'make htmldocs' in a virtualenv constructed from Documentation/sphinx/requirements.txt: Sphinx version error: The alabaster extension used by this project needs at least Sphinx v3.4; it therefore cannot be built with this version. Raising the Sphinx version is not really a good option at this point, since 3.x through 6.x have horrible performance regressions (7.x still does, but not quite as bad). Instead, constrain the 'alabaster' package to versions that still support Sphinx 2.4.4. Signed-off-by: Vegard Nossum <[email protected]> Link: https://lore.kernel.org/r/[email protected] Signed-off-by: Jonathan Corbet <[email protected]>
* | Merge tag 'docs-6.8' of git://git.lwn.net/linuxLinus Torvalds2024-01-126-64/+148
|\| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Pull documentation update from Jonathan Corbet: "Another moderately busy cycle for documentation, including: - The minimum Sphinx requirement has been raised to 2.4.4, following a warning that was added in 6.2 - Some reworking of the Documentation/process front page to, hopefully, make it more useful - Various kernel-doc tweaks to, for example, make it deal properly with __counted_by annotations - We have also restored a warning for documentation of nonexistent structure members that disappeared a while back. That had the delightful consequence of adding some 600 warnings to the docs build. A sustained effort by Randy, Vegard, and myself has addressed almost all of those, bringing the documentation back into sync with the code. The fixes are going through the appropriate maintainer trees - Various improvements to the HTML rendered docs, including automatic links to Git revisions and a nice new pulldown to make translations easy to access - Speaking of translations, more of those for Spanish and Chinese ... plus the usual stream of documentation updates and typo fixes" * tag 'docs-6.8' of git://git.lwn.net/linux: (57 commits) MAINTAINERS: use tabs for indent of CONFIDENTIAL COMPUTING THREAT MODEL A reworked process/index.rst ring-buffer/Documentation: Add documentation on buffer_percent file Translated the RISC-V architecture boot documentation. Docs: remove mentions of fdformat from util-linux Docs/zh_CN: Fix the meaning of DEBUG to pr_debug() Documentation: move driver-api/dcdbas to userspace-api/ Documentation: move driver-api/isapnp to userspace-api/ Documentation/core-api : fix typo in workqueue Documentation/trace: Fixed typos in the ftrace FLAGS section kernel-doc: handle a void function without producing a warning scripts/get_abi.pl: ignore some temp files docs: kernel_abi.py: fix command injection scripts/get_abi: fix source path leak CREDITS, MAINTAINERS, docs/process/howto: Update man-pages' maintainer docs: translations: add translations links when they exist kernel-doc: Align quick help and the code MAINTAINERS: add reviewer for Spanish translations docs: ignore __counted_by attribute in structure definitions scripts: kernel-doc: Clarify missing struct member description ..
| * docs: kernel_abi.py: fix command injectionVegard Nossum2024-01-031-46/+10
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | The kernel-abi directive passes its argument straight to the shell. This is unfortunate and unnecessary. Let's always use paths relative to $srctree/Documentation/ and use subprocess.check_call() instead of subprocess.Popen(shell=True). This also makes the code shorter. Link: https://fosstodon.org/@jani/111676532203641247 Reported-by: Jani Nikula <[email protected]> Cc: [email protected] Signed-off-by: Vegard Nossum <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/[email protected]
| * docs: translations: add translations links when they existVegard Nossum2023-12-192-0/+116
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Add a new Sphinx extension that knows about the translations of kernel documentation and can insert links to the translations at the top of the document. It basically works like this: 1. Register a new node type, LanguagesNode. 2. Register a new transform, TranslationsTransform, that inserts a new LanguageNode at the top of every document. The LanguageNode contains "pending references" to translations of the document. The key here is that these are pending (i.e. unresolved) references that may or may not actually exist. 3. Register a 'doctree-resolved' event that iterates over all the LanguageNode nodes. Any unresolved references are filtered out; the list of resolved references is passed to the 'translations.html' template and rendered as an HTML node (if HTML output is selected). Testing: make htmldocs, make latexdocs with Sphinx v4.3.2 and Firefox. v2: - changed bar into a drop-down menu - fixed language labels - fixed hysteresis reported by Akira Yokosawa Cc: Federico Vaga <[email protected]> Cc: Jani Nikula <[email protected]> Cc: Akira Yokosawa <[email protected]> Cc: Yanteng Si <[email protected]> Signed-off-by: Vegard Nossum <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/[email protected]
| * docs: Raise the minimum Sphinx requirement to 2.4.4Jonathan Corbet2023-12-153-17/+3
| | | | | | | | | | | | | | | | | | | | | | | | Commit 31abfdda6527 (docs: Deprecate use of Sphinx < 2.4.x) in 6.2 added a warning that support for older versions of Sphinx would be going away. There have been no complaints, so the time has come. Raise the minimum Sphinx version to 2.4.4 and clean out some compatibility code that we no longer need. Reviewed-by: Mauro Carvalho Chehab <[email protected]> Link: https://lore.kernel.org/r/[email protected] Signed-off-by: Jonathan Corbet <[email protected]>
| * docs: automarkup: linkify git revsVegard Nossum2023-11-171-1/+19
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | There aren't a ton of references to commits in the documentation, but they do exist, and we can use automarkup to linkify them to make them easier to follow. Use something like this to find references to commits: git grep -P 'commit.*[0-9a-f]{8,}' Documentation/ Also fix a few of these to standardize on the exact format that is already used in changelogs. Signed-off-by: Vegard Nossum <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/[email protected]
* | Documentation: add pyyaml to requirements.txtVegard Nossum2024-01-021-0/+1
|/ | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Commit f061c9f7d058 ("Documentation: Document each netlink family") added a new Python script that is invoked during 'make htmldocs' and which reads the netlink YAML spec files. Using the virtualenv from scripts/sphinx-pre-install, we get this new error wen running 'make htmldocs': Traceback (most recent call last): File "./tools/net/ynl/ynl-gen-rst.py", line 26, in <module> import yaml ModuleNotFoundError: No module named 'yaml' make[2]: *** [Documentation/Makefile:112: Documentation/networking/netlink_spec/rt_link.rst] Error 1 make[1]: *** [Makefile:1708: htmldocs] Error 2 Fix this by adding 'pyyaml' to requirements.txt. Note: This was somehow present in the original patch submission: <https://lore.kernel.org/all/[email protected]/> I'm not sure why the pyyaml requirement disappeared in the meantime. Fixes: f061c9f7d058 ("Documentation: Document each netlink family") Cc: Breno Leitao <[email protected]> Cc: Jakub Kicinski <[email protected]> Cc: David S. Miller <[email protected]> Cc: Jonathan Corbet <[email protected]> Signed-off-by: Vegard Nossum <[email protected]> Reviewed-by: Simon Horman <[email protected]> Signed-off-by: David S. Miller <[email protected]>
* Documentation/sphinx: Remove the repeated word "the" in comments.Charles Han2023-10-231-1/+1
| | | | | | | | Remove the repeated word "the" in comments. Signed-off-by: Charles Han <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Message-ID: <[email protected]>
* docs/sphinx: Explicitly convert Sphinx paths to strOliver Faso2023-10-102-2/+2
| | | | | | | | | | | | | Sphinx 7.2+ is switching to using pathlib.Path instead of str to represent paths. This fixes the current deprecation warnings and eventual breakage. This conversion will be a no-op when using older Sphinx versions. Signed-off-by: Oliver Faso <[email protected]> Tested-by: Akira Yokosawa <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/[email protected]
* Documentation/sphinx: fix Python string escapesBenjamin Gray2023-09-125-8/+8
| | | | | | | | | | | | 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 <[email protected]> Message-ID: <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]>
* Documentation: Fix typosBjorn Helgaas2023-08-181-1/+1
| | | | | | | | Fix typos in Documentation. Signed-off-by: Bjorn Helgaas <[email protected]> Link: https://lore.kernel.org/r/[email protected] Signed-off-by: Jonathan Corbet <[email protected]>
generated by cgit (git 2.51.2) at 2025-12-01 17:58:44 +0000