summaryrefslogtreecommitdiffstats
path: root/Documentation/sphinx
Commit message (Collapse)AuthorAgeFilesLines
* 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/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>
* 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 <akiyks@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <ed1ec6f2-0050-46f6-807d-8679f26427e9@gmail.com>
* 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/54a56c2e-a27c-45a0-b712-02a7bc7d2673@gmail.com/ Fixes: 7418ec5b151f ("docs: translations: add translations links when they exist") Reported-by: Akira Yokosawa <akiyks@gmail.com> Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com> Closes: https://lore.kernel.org/all/54a56c2e-a27c-45a0-b712-02a7bc7d2673@gmail.com/ Tested-by: Akira Yokosawa <akiyks@gmail.com> # Sphinx 4.3.2, 5.3.0 and 6.2.1 Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20240215064109.1193556-1-vegard.nossum@oracle.com
| * 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 <jforbes@fedoraproject.org> Cc: Salvatore Bonaccorso <carnil@debian.org> Cc: Jani Nikula <jani.nikula@intel.com> Cc: Mauro Carvalho Chehab <mchehab@kernel.org> Cc: stable@vger.kernel.org Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com> Link: https://lore.kernel.org/r/20240205175133.774271-2-vegard.nossum@oracle.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* | 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 <jforbes@fedoraproject.org> Cc: Salvatore Bonaccorso <carnil@debian.org> Cc: Jani Nikula <jani.nikula@intel.com> Cc: Mauro Carvalho Chehab <mchehab@kernel.org> Cc: stable@vger.kernel.org Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com> Link: https://lore.kernel.org/r/20240205175133.774271-2-vegard.nossum@oracle.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* | 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 <jani.nikula@intel.com> Cc: Mauro Carvalho Chehab <mchehab@kernel.org> Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com> Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20240215134828.1277109-6-vegard.nossum@oracle.com
* 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 <gustavo.sousa@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20240123162157.61819-2-gustavo.sousa@intel.com
* 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 <jani.nikula@intel.com> Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com> Cc: stable@vger.kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20240110174758.3680506-1-vegard.nossum@oracle.com
| * 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 <vegard.nossum@oracle.com> Link: https://lore.kernel.org/r/20240110104646.3647600-1-vegard.nossum@oracle.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* | Merge tag 'docs-6.8' of git://git.lwn.net/linuxLinus Torvalds2024-01-116-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 <jani.nikula@intel.com> Cc: stable@vger.kernel.org Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20231231235959.3342928-2-vegard.nossum@oracle.com
| * 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 <federico.vaga@vaga.pv.it> Cc: Jani Nikula <jani.nikula@linux.intel.com> Cc: Akira Yokosawa <akiyks@gmail.com> Cc: Yanteng Si <siyanteng@loongson.cn> Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20231215123701.2712807-1-vegard.nossum@oracle.com
| * 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 <mchehab@kernel.org> Link: https://lore.kernel.org/r/874jgs47fq.fsf@meer.lwn.net Signed-off-by: Jonathan Corbet <corbet@lwn.net>
| * 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 <vegard.nossum@oracle.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20231027115420.205279-1-vegard.nossum@oracle.com
* | 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/20231103135622.250314-1-leitao@debian.org/> I'm not sure why the pyyaml requirement disappeared in the meantime. Fixes: f061c9f7d058 ("Documentation: Document each netlink family") Cc: Breno Leitao <leitao@debian.org> Cc: Jakub Kicinski <kuba@kernel.org> Cc: David S. Miller <davem@davemloft.net> Cc: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com> Reviewed-by: Simon Horman <horms@kernel.org> Signed-off-by: David S. Miller <davem@davemloft.net>
* Documentation/sphinx: Remove the repeated word "the" in comments.Charles Han2023-10-221-1/+1
| | | | | | | | Remove the repeated word "the" in comments. Signed-off-by: Charles Han <hanchunchao@inspur.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <20231018023046.30022-1-hanchunchao@inspur.com>
* 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 <erer1243@gmail.com> Tested-by: Akira Yokosawa <akiyks@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20230910040811.53046-1-erer1243@gmail.com
* 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 <bgray@linux.ibm.com> Message-ID: <20230912060801.95533-3-bgray@linux.ibm.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* Documentation: Fix typosBjorn Helgaas2023-08-181-1/+1
| | | | | | | | Fix typos in Documentation. Signed-off-by: Bjorn Helgaas <bhelgaas@google.com> Link: https://lore.kernel.org/r/20230814212822.193684-4-helgaas@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: Use HTML comments for the kernel-toc SPDX lineJonathan Corbet2023-02-161-1/+1
| | | | | | | | | This line was initially placed in {# jinja2 comments #}, but that led to an "invalid token" complaint from spdxcheck.py. Rather than fix the script for a usage we'll likely never see anywhere else, just switch to an HTML comment, which spdxcheck.py thinks is fine. Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: Add more information to the HTML sidebarJonathan Corbet2023-02-081-0/+16
| | | | | | | | | | | | | | Add a new sidebar template that creates a more RTD-like "fisheye" view of the current place in the document hierarchy. It is far from ideal, but some readers may find it better for navigating through the documentation as a whole. Add some CSS trickery as well to make the table of contents less intrusive when viewing the pages on a small screen. Reviewed-by: Akira Yokosawa <akiyks@gmail.com> Reviewed-by: David Gow <davidgow@google.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: Fix the docs build with Sphinx 6.0Jonathan Corbet2023-01-061-2/+4
| | | | | | | | | | | | | Sphinx 6.0 removed the execfile_() function, which we use as part of the configuration process. They *did* warn us... Just open-code the functionality as is done in Sphinx itself. Tested (using SPHINX_CONF, since this code is only executed with an alternative config file) on various Sphinx versions from 2.5 through 6.0. Reported-by: Martin Liška <mliska@suse.cz> Cc: stable@vger.kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: sphinx-pre-install: don't require the RTD themeJonathan Corbet2022-10-131-1/+0
| | | | | | | | We don't default to the RTD theme anymore, so sphinx-pre-install need not insist on installing it. Acked-by: Mauro Carvalho Chehab <mchehab@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: kerneldoc-preamble: Test xeCJK.sty before loadingAkira Yokosawa2022-08-181-6/+16
| | | | | | | | | | | | | | | | | | | | | | | | On distros whose texlive packaging is fine-grained, texlive-xecjk can be installed/removed independently of other texlive packages. Conditionally loading xeCJK depending only on the existence of the "Noto Sans CJK SC" font might end up in xelatex error of "xeCJK.sty not found!". Improve the situation by testing existence of xeCJK.sty before loading it. This is useful on RHEL 9 and its clone distros where texlive-xecjk doesn't work at the moment due to a missing dependency [1]. "make pdfdocs" for non-CJK contents should work after removing texlive-xecjk. Link: [1] https://bugzilla.redhat.com/show_bug.cgi?id=2086254 Fixes: 398f7abdcb7e ("docs: pdfdocs: Pull LaTeX preamble part out of conf.py") Cc: stable@vger.kernel.org # v5.18+ Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Acked-by: Mauro Carvalho Chehab <mchehab@kernel.org> Link: https://lore.kernel.org/r/c24c2a87-70b2-5342-bcc9-de467940466e@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: automarkup: do not look up symbols twiceJonathan Corbet2022-07-071-31/+26
| | | | | | | | | | | | The automarkup code tries to look up symbols once as a function, and once as a macro. The Sphinx C domain code, though, totally ignores that distinction and will return the same results either way. So just look things up once and be done with it; the resulting output does not change, but htmldocs build time drops by about 5%. Tested-by: Akira Yokosawa <akiyks@gmail.com> Link: https://lore.kernel.org/r/20220630163630.714673-3-corbet@lwn.net Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: automarkup: track failed cross-reference attemptsJonathan Corbet2022-07-071-0/+13
| | | | | | | | | | | | | | The automarkup code tries to create a lot of cross-references that don't exist. Cross-reference lookups are expensive, especially in later versions of Sphinx, so there is value in avoiding unnecessary ones. Remember attempts that failed and do not retry them. This improves the htmldocs build time by 5-10% depending on the phase of the moon and other factors. Tested-by: Akira Yokosawa <akiyks@gmail.com> Link: https://lore.kernel.org/r/20220630163630.714673-2-corbet@lwn.net Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: pdfdocs: Add space for chapter counts >= 100 in TOCAkira Yokosawa2022-05-171-7/+7
| | | | | | | | | | | | | | | It turns out that networking.pdf has exceeded 100 chapters and titles of chapters >= 100 collide with their counts in its table of contents (TOC). Increase relevant params by 0.6em in the preamble to avoid such ugly collisions. While at it, fix a typo in comment (subsection). Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Link: https://lore.kernel.org/r/bdb60ba3-7813-47d0-74f9-7c31dd912d95@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: sphinx/requirements: Limit jinja2<3.1Akira Yokosawa2022-03-301-0/+2
| | | | | | | | | | | | | | | jinja2 release 3.1.0 (March 24, 2022) broke Sphinx<4.0. This looks like the result of deprecating Python 3.6. It has been tested against Sphinx 4.3.0 and later. Setting an upper limit of <3.1 to junja2 can unbreak Sphinx<4.0 including Sphinx 2.4.4. Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Cc: Mauro Carvalho Chehab <mchehab@kernel.org> Cc: stable@vger.kernel.org # v5.15+ Link: https://lore.kernel.org/r/7dbff8a0-f4ff-34a0-71c7-1987baf471f9@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* scripts/kernel-doc: change the line number meta infoMauro Carvalho Chehab2022-03-281-1/+1
| | | | | | | | | | | | | | | | In order to make it more standard and ReST compatible, change the meta-tag used with --enable-lineno from: #define LINENO to .. LINENO In practice, no functional changes. Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org> Link: https://lore.kernel.org/r/40725032b5a4a33db740bf1de397523af958ff8a.1648290305.git.mchehab@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* scripts/get_abi: change the file/line number meta infoMauro Carvalho Chehab2022-03-281-1/+1
| | | | | | | | | | | | | | | | In order to make it more standard and ReST compatible, change the meta-tag used with --enable-lineno from: #define LINENO to .. LINENO In practice, no functional changes. Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org> Link: https://lore.kernel.org/r/125ffd31fbc77ad9eee4d6906e1830b8162fa6ca.1648290305.git.mchehab@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: kernel_include.py: add sphinx build dependenciesMauro Carvalho Chehab2022-03-281-0/+3
| | | | | | | | | | The files included by kernel-include should be added as build dependencies, in order for sphinx-build to rebuild the corresponding docs if any changes at the included file happens. Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org> Link: https://lore.kernel.org/r/d30fc4fa422a13b7e1623d690945c46b58a55e79.1648290305.git.mchehab@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: kernel_abi.py: add sphinx build dependenciesMauro Carvalho Chehab2022-03-281-0/+4
| | | | | | | | | | | Ensure that Sphinx-build will handle the files parsed by get_abi.pl as dependencies. This way, if they are touched, the ABI output will be regenerated. Reported-by: Hans de Goede <hdegoede@redhat.com> Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org> Link: https://lore.kernel.org/r/10bc3d3bc74f514a539cd3b48b9d287d2b6f99e2.1648290305.git.mchehab@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: kernel_feat.py: add build dependenciesMauro Carvalho Chehab2022-03-281-2/+18
| | | | | | | | | | Ensure that the feature files will be regenerated if any changes happen at the Documentation/features files that were processed by gen_feat.pl. Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org> Link: https://lore.kernel.org/r/5cdf7a8300019129dcc09d4c2557f75908754445.1648290305.git.mchehab@kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: kfigure.py: Don't warn of missing PDF converter in 'make htmldocs'Akira Yokosawa2022-03-281-3/+5
| | | | | | | | | | | | | | | | | | | | SVG -> PDF conversion is not required in "make htmldocs". It is pointless to always warn of a missing converter. Demote the log message in setupTools() to verbose. For "make pdfdocs" (or "make latexdocs"), promote the dynamic message of "include SVG raw" to a warn. Expand the message and recommend installing Inkscape or ImageMagick. Fixes: 8ccd05697a9d ("docs: sphinx/kfigure.py: Use inkscape(1) for SVG -> PDF conversion") Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Cc: Jonathan Corbet <corbet@lwn.net> Cc: Mauro Carvalho Chehab <mchehab@kernel.org> Cc: linux-doc@vger.kernel.org Acked-by: Mauro Carvalho Chehab <mchehab@kernel.org> Link: https://lore.kernel.org/r/c80e1481-10d4-7151-fe59-e846259eb0d4@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* Reword note on missing CJK fontsAkira Yokosawa2022-02-241-3/+10
| | | | | | | | | | | Use past tense as the fonts can be installed after the fact. Add suggestion to install "Noto Sans CJK" and "Noto Serif CJK" font families. ("Noto Serif CJK" is optional.) Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Cc: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/dfefa601-c58d-c86c-953f-5e4454db9409@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: kerneldoc-preamble.sty: Expand comments in LaTeX codeAkira Yokosawa2022-02-241-13/+48
| | | | | | | | | | | | | Expand comments in LaTeX code and mention some of important points told in changelogs of conf.py changes. Hopefully they can help future contributors in this area. No code change involved. Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Cc: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/bce9261b-1950-3146-07b2-07bd2ec79158@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: pdfdocs: Pull LaTeX preamble part out of conf.pyAkira Yokosawa2022-02-241-0/+184
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Quote from Jon's remark [1]: I do notice that Documentation/conf.py is getting large and unapproachable. At some future point, it might be nice to pull all of the latex stuff out into a separate file where it won't scare people who stumble into it by accident. Pull LaTeX preamble settings added since commit 3b4c963243b1 ("docs: conf.py: adjust the LaTeX document output") out into sphinx/kerneldoc-preamble.sty. It will be copied to the build directory by the added "latex_additional_files" setting in conf.py. As a bonus, LaTeX/TeX code can be maintained without escaping backslashes. To compensate the loss of change history in sphinx/kerneldoc-preamble.sty, here is a list of changes made in conf.py: - f7ebe6b76940 ("docs: Activate exCJK only in CJK chapters") - 0afd4df0d16a ("docs: pdfdocs: Prevent column squeezing by tabulary") - 659653c9e546 ("docs: pdfdocs: Refactor config for CJK document") - e291ff6f5a03 ("docs: pdfdocs: Add CJK-language-specific font settings") - 7eb368cc319b ("docs: pdfdocs: Choose Serif font as CJK mainfont if possible") - 35382965bdd2 ("docs: pdfdocs: Preserve inter-phrase space in Korean translations") - 77abc2c230b1 ("docs: pdfdocs: One-half spacing for CJK translations") - 788d28a25799 ("docs: pdfdocs: Permit AutoFakeSlant for CJK fonts") - 29ac9822358f ("docs: pdfdocs: Teach xeCJK about character classes of quotation marks") - 7c5c18bdb656 ("docs: pdfdocs: Fix typo in CJK-language specific font settings") - aa872e0647dc ("docs: pdfdocs: Adjust \headheight for fancyhdr") - 8716ef413aa5 ("docs: pdfdocs: Tweak width params of TOC") - 66939df53948 ("docs: pdfdocs: Switch default CJK font to KR variants") - 7b686a2ea1e4 ("docs: pdfdocs: Enable CJKspace in TOC for Korean titles") - 5d9158e3c762 ("docs/translations: Skip CJK contents if suitable fonts not found") - b774cc46313b ("docs: pdfdocs: Move CJK monospace font setting to main conf.py") [1]: https://lore.kernel.org/all/87zgmr66cn.fsf@meer.lwn.net/ Suggested-by: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Link: https://lore.kernel.org/r/aaa9dca1-27c0-c414-77f3-c5587db0cc5b@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: sphinx/kfigure.py: Delegate inkscape msg to kernellog.verboseAkira Yokosawa2022-02-091-3/+19
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Depending on its version, distro config, and system-setup type, inkscape(1) emits various warning messages which are harmless in command-line uses. List of such warning messages (incomplete, long ones wrapped): - Gtk-Message: hh:mm:ss.nnn: Failed to load module "canberra-gtk-module" - Unable to init server: Could not connect: Connection refused - Failed to get connection - ** (inkscape:xxx): CRITICAL **: hh:mm:ss.nnn: dbus_g_proxy_new_for_name: assertion 'connection != NULL' failed - ** (inkscape:xxx): CRITICAL **: hh:mm:ss.nnn: dbus_g_proxy_call: assertion 'DBUS_IS_G_PROXY (proxy)' failed - ** (inkscape:xxx): CRITICAL **: hh:mm:ss.nnn: dbus_g_connection_register_g_object: assertion 'connection != NULL' failed - ** (inkscape:xxx): WARNING **: hh:mm:ss.nnn: Fonts dir '/usr/share/inkscape/fonts' does not exist and will be ignored. To avoid unnecessary anxiety, capture the message and output it via kernellog.verbose or kernellog.warn depending on the exit code. Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Cc: Jonathan Corbet <corbet@lwn.net> Cc: Mauro Carvalho Chehab <mchehab@kernel.org> Cc: Randy Dunlap <rdunlap@infradead.org> Link: https://lore.kernel.org/r/e26a7b53-9155-8394-4a31-6006379b65a5@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: sphinx/kfigure.py: Use inkscape(1) for SVG -> PDF conversionAkira Yokosawa2022-02-091-20/+48
| | | | | | | | | | | | | | | | | | | | | | | | | | | | Using convert(1) of ImageMagick for SVG -> PDF conversion results in PDFs containing raster (bitmap) images which sometimes look blurry. Ideally speaking, SVG to PDF conversion should retain vector graphics in SVG. rsvg-convert(1) can do such conversions with regard to SVG files generated by dot(1). Unfortunately, rsvg-convert(1) does not cover some of SVG features specific to Inkscape. inkscape(1) of Inkscape naturally covers such SVG features. So add a route in svg2pdf() so that inkscape(1) is used when it is available. Note: After this change, if you have Inkscape installed, ImageMagick nor librsvg are not required. Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Cc: Jonathan Corbet <corbet@lwn.net> Cc: Mauro Carvalho Chehab <mchehab@kernel.org> Link: https://lore.kernel.org/r/3eea2a8d-c52d-ee07-cf7b-83784c6f6e4b@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: sphinx/kfigure.py: Add check of 'dot -Tpdf'Akira Yokosawa2022-02-091-4/+26
| | | | | | | | | | | | | | | | | | To prevent any regression on existing build systems, limit the fallback of converting DOT -> raster PDF only when both of the following conditions are met. o dot(1) doesn't support -Tpdf o rsvg-convert(1) is not found While we are here, add kernellog.verbose messages related to rsvg-convert, 'dot -Tpdf', and 'dot -Tsvg' commands. Suggested-by: Mauro Carvalho Chehab <mchehab@kernel.org> Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Cc: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/e76f61e1-7366-ba00-b119-8ea6a2499861@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: sphinx/kfigure.py: Use rsvg-convert(1) for DOT -> PDF conversionAkira Yokosawa2022-02-091-2/+44
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | On openSUSE, dot(1) command does not support direct PDF output. On other distros, generated PDF images have unnecessarily wide margins, especially for small graphs. By using dot(1) for DOT -> SVG, then rsvg-convert(1) for SVG -> PDF, more optimal PDF images can be obtained, with the bonus of improved portability across various distros. Add rules in kfigure.py so that the above mentioned route is taken when rsvg-convert(1) is available. Note that rsvg-convert(1) is recommended by sphinx_pre_install. So it is most likely that existing systems for building pdfdocs have rsvg-convert(1) installed. Note: SVG features supported by rsvg-convert(1) vary depending on its version and distro config. For example, the one found on Ubuntu Bionic (version 2.40.20) does poor job in rendering some of SVG files drawn by Inkscape. SVG files generated by dot(1) are converted nicely even with such old versions of rsvg-convert. So this change does not affect the quality of such figures in any way. Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Cc: Jonathan Corbet <corbet@lwn.net> Cc: Mauro Carvalho Chehab <mchehab@kernel.org> Link: https://lore.kernel.org/r/15b56dd3-081a-2469-c3a4-dfc1ca4c6c2d@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: automarkup.py: Fix invalid HTML link output and broken URI fragmentsJames Clark2022-01-071-7/+18
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Since commit d18b01789ae5 ("docs: Add automatic cross-reference for documentation pages"), references that were already explicitly defined with "ref:" and referred to other pages with a path have been doubled. This is reported as the following error by Firefox: Start tag "a" seen but an element of the same type was already open. End tag "a" violates nesting rules. As well as the invalid HTML, this also obscures the URI fragment links to subsections because the second link overrides the first. For example on the page admin-guide/hw-vuln/mds.html the last link should be to the "Default Mitigations" subsection using a # URI fragment: admin-guide/hw-vuln/l1tf.html#default-mitigations But it is obsured by a second link to the whole page: admin-guide/hw-vuln/l1tf.html The full HTML with the double <a> tags looks like this: <a class="reference internal" href="l1tf.html#default-mitigations"> <span class="std std-ref"> <a class="reference internal" href="l1tf.html"> <span class="doc">L1TF - L1 Terminal Fault</span> </a> </span> </a> After this commit, there is only a single link: <a class="reference internal" href="l1tf.html#default-mitigations"> <span class="std std-ref">Documentation/admin-guide/hw-vuln//l1tf.rst</span> </a> Now that the second link is removed, the browser correctly jumps to the default-mitigations subsection when clicking the link. The fix is to check that nodes in the document to be modified are not already references. A reference is counted as any text that is a descendant of a reference type node. Only plain text should be converted to new references, otherwise the doubling occurs. Testing ======= * Test that the build stdout is the same (ignoring ordering), and that no new warnings are printed. * Diff all .html files and check that the only modifications occur to the bad double links. * The auto linking of bare references to pages without "ref:" is still working. Fixes: d18b01789ae5 ("docs: Add automatic cross-reference for documentation pages") Reviewed-by: Nícolas F. R. A. Prado <n@nfraprado.net> Signed-off-by: James Clark <james.clark@arm.com> Link: https://lore.kernel.org/r/20220105143640.330602-2-james.clark@arm.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* Documentation/sphinx: fix typos of "its"Randy Dunlap2021-12-232-2/+2
| | | | | | | | | | Use "its" for possessive form instead of the contraction "it's". Signed-off-by: Randy Dunlap <rdunlap@infradead.org> Cc: Jonathan Corbet <corbet@lwn.net> Cc: linux-doc@vger.kernel.org Link: https://lore.kernel.org/r/20211222062354.23224-1-rdunlap@infradead.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: sphinx-requirements: Move sphinx_rtd_theme to topAkira Yokosawa2021-08-121-2/+1
| | | | | | | | | | | | | | | | | | sphinx_rtd_theme 0.5.2 has "docutils<0.17" in its requirements. docutils 0.17 released this April caused regression in sphinx_rtd_theme 0.5.1 [1]. By removing docutils and moving sphinx_rtd_theme before Sphinx in requirements.txt, the requirement of "docutils<0.17" can be met naturally. [1]: https://github.com/readthedocs/sphinx_rtd_theme/issues/1112 Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Cc: Mauro Carvalho Chehab <mchehab@kernel.org> Acked-by: Mauro Carvalho Chehab <mchehab@kernel.org> Link: https://lore.kernel.org/r/75f14c88-6091-1072-41cb-16b886aee5a0@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: sphinx: Fix couple of spellings in the file rstFlatTable.pyBhaskar Chowdhury2021-03-061-2/+2
| | | | | | | | | | | | s/automaticly/automatically/ s/buidler/builder/ ..and a sentence construction fix. Signed-off-by: Bhaskar Chowdhury <unixbhaskar@gmail.com> Acked-by: Randy Dunlap <rdunlap@infradead.org> Link: https://lore.kernel.org/r/20210301201052.11067-1-unixbhaskar@gmail.com Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* docs: Enable usage of relative paths to docs on automarkupNícolas F. R. A. Prado2021-02-041-2/+5
| | | | | | | | | | | | | | | | | | | | Previously, a cross-reference to another document could only be created by writing the full path to the document starting from the Documentation/ directory. Extend this to also allow relative paths to be used. A relative path would be just the path, like ../filename.rst, while the absolute path still needs to start from Documentation, like Documentation/filename.rst. As part of this change, the .rst extension is now required for both types of paths, since not requiring it would cause the regex to be too generic. Suggested-by: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Nícolas F. R. A. Prado <nfraprado@protonmail.com> Link: https://lore.kernel.org/r/20210128010028.58541-2-nfraprado@protonmail.com [jc: Tweaked the regex to recognize .txt too] Signed-off-by: Jonathan Corbet <corbet@lwn.net>
* Docs: drop Python 2 supportJonathan Corbet2021-02-014-26/+1
| | | | | | | | | 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>
* Move our minimum Sphinx version to 1.7Jonathan Corbet2021-02-015-94/+18
| | | | | | | As promised, drop support for some ancient sphinx releases, along with a lot of the cruft that was required to make that support work. Signed-off-by: Jonathan Corbet <corbet@lwn.net>
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-06 16:18:16 +0000