linux/Documentation/sphinx, branch v6.8

docs: translations: use attribute to store current language

2024-02-21T20:41:37Z

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/54a56c2e-a27c-45a0-b712-02a7bc7d2673@gmail.com/ Fixes: 7418ec5b151f ("docs: translations: add translations links when they exist") Reported-by: Akira Yokosawa Signed-off-by: Vegard Nossum Closes: https://lore.kernel.org/all/54a56c2e-a27c-45a0-b712-02a7bc7d2673@gmail.com/ Tested-by: Akira Yokosawa # Sphinx 4.3.2, 5.3.0 and 6.2.1 Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240215064109.1193556-1-vegard.nossum@oracle.com

docs: kernel_feat.py: fix build error for missing files

2024-02-08T18:05:35Z

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 Cc: Salvatore Bonaccorso Cc: Jani Nikula Cc: Mauro Carvalho Chehab Cc: stable@vger.kernel.org Signed-off-by: Vegard Nossum Link: https://lore.kernel.org/r/20240205175133.774271-2-vegard.nossum@oracle.com Signed-off-by: Jonathan Corbet

docs/sphinx: Fix TOC scroll hack for the home page

2024-01-23T21:33:13Z

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 Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240123162157.61819-2-gustavo.sousa@intel.com

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

2024-01-17T19:49:11Z

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

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

2024-01-12T03:46:52Z

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_feat.py: fix potential command injection

2024-01-11T16:21:01Z

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 Signed-off-by: Vegard Nossum Cc: stable@vger.kernel.org Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240110174758.3680506-1-vegard.nossum@oracle.com

Documentation: constrain alabaster package to older versions

2024-01-11T16:17:23Z

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 Link: https://lore.kernel.org/r/20240110104646.3647600-1-vegard.nossum@oracle.com Signed-off-by: Jonathan Corbet

docs: kernel_abi.py: fix command injection

2024-01-03T20:44:11Z

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 Cc: stable@vger.kernel.org Signed-off-by: Vegard Nossum Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20231231235959.3342928-2-vegard.nossum@oracle.com

Documentation: add pyyaml to requirements.txt

2024-01-02T13:41:24Z

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 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: I'm not sure why the pyyaml requirement disappeared in the meantime. Fixes: f061c9f7d058 ("Documentation: Document each netlink family") Cc: Breno Leitao Cc: Jakub Kicinski Cc: David S. Miller Cc: Jonathan Corbet Signed-off-by: Vegard Nossum Reviewed-by: Simon Horman Signed-off-by: David S. Miller

docs: translations: add translations links when they exist

2023-12-19T21:34:59Z

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 Cc: Jani Nikula Cc: Akira Yokosawa Cc: Yanteng Si Signed-off-by: Vegard Nossum Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20231215123701.2712807-1-vegard.nossum@oracle.com