kernel/linux.git/Documentation/conf.py, branch v6.6.132

docs: Restore "smart quotes" for quotes

2024-04-03T13:28:22+00:00

[ Upstream commit fe2562582bffe675721e77e00b3bf5bfa1d7aeab ] Commit eaae75754d81 ("docs: turn off "smart quotes" in the HTML build") disabled conversion of quote marks along with that of dashes. Despite the short summary, the change affects not only HTML build but also other build targets including PDF. However, as "smart quotes" had been enabled for more than half a decade already, quite a few readers of HTML pages are likely expecting conversions of "foo" -> “foo” and 'bar' -> ‘bar’. Furthermore, in LaTeX typesetting convention, it is common to use distinct marks for opening and closing quote marks. To satisfy such readers' expectation, restore conversion of quotes only by setting smartquotes_action [1]. Link: [1] https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-smartquotes_action Cc: stable@vger.kernel.org # v6.4 Signed-off-by: Akira Yokosawa Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240225094600.65628-1-akiyks@gmail.com Signed-off-by: Sasha Levin

docs: Instruct LaTeX to cope with deeper nesting

2024-03-01T12:34:58+00:00

commit 0df8669f69a8638f04c6a3d1f3b7056c2c18f62c upstream. The addition of the XFS online fsck documentation starting with commit a8f6c2e54ddc ("xfs: document the motivation for online fsck design") added a deeper level of nesting than LaTeX is prepared to deal with. That caused a pdfdocs build failure with the helpful "Too deeply nested" error message buried deeply in Documentation/output/filesystems.log. Increase the "maxlistdepth" parameter to instruct LaTeX that it needs to deal with the deeper nesting whether it wants to or not. Suggested-by: Akira Yokosawa Tested-by: Akira Yokosawa Cc: stable@vger.kernel.org # v6.4+ Link: https://lore.kernel.org/linux-doc/67f6ac60-7957-4b92-9d72-a08fbad0e028@gmail.com/ Signed-off-by: Jonathan Corbet Signed-off-by: Greg Kroah-Hartman

Documentation: conf.py: Add __force to c_id_attributes

2023-05-19T14:58:10+00:00

Fixes the following error in the docs build that occurs with recent versions of Sphinx when parsing kerneldocs for a function with the '__force' macro in its signature: ./include/linux/err.h:51: WARNING: Error in declarator or parameters Error in declarator or parameters Invalid C declaration: Expected identifier, got keyword: void [error at 35] void * ERR_CAST (__force const void *ptr) -----------------------------------^ Currently, almost all of the few in-signature occurrences of '__force' are in the error pointer functions. Of those, ERR_CAST() is the only one with kerneldocs, but the kerneldocs aren't even being used to generate documentation. This change will allow all the error pointer functions to be properly documented. In addition to '__force', also defines '__nocast', '__safe', and '__private'. These are not currently used in any function signatures and do not need to be added to the docs config. Signed-off-by: James Seo Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20230509175543.2065835-2-james@equiv.tech

docs: turn off "smart quotes" in the HTML build

2023-04-20T23:53:18+00:00

We have long disabled the "html_use_smartypants" option to prevent Sphinx from mangling "--" sequences (among others). Unfortunately, Sphinx changed that option to "smartquotes" in the 1.6.6 release, and seemingly didn't see fit to warn about the use of the obsolete option, resulting in the aforementioned mangling returning. Disable this behavior again and hope that the option name stays stable for a while. Reported-by: Zipeng Zhang Link: https://lore.kernel.org/lkml/tencent_CB1A298D31FD221496FF657CD7EF406E6605@qq.com Reviewed-by: Miguel Ojeda Signed-off-by: Jonathan Corbet

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

2023-02-22T20:00:20+00:00

Pull documentation updates from Jonathan Corbet: "It has been a moderately calm cycle for documentation; the significant changes include: - Some significant additions to the memory-management documentation - Some improvements to navigation in the HTML-rendered docs - More Spanish and Chinese translations ... and the usual set of typo fixes and such" * tag 'docs-6.3' of git://git.lwn.net/linux: (68 commits) Documentation/watchdog/hpwdt: Fix Format Documentation/watchdog/hpwdt: Fix Reference Documentation: core-api: padata: correct spelling docs/mm: Physical Memory: correct spelling in reference to CONFIG_PAGE_EXTENSION docs: Use HTML comments for the kernel-toc SPDX line docs: Add more information to the HTML sidebar Documentation: KVM: Update AMD memory encryption link printk: Document that CONFIG_BOOT_PRINTK_DELAY required for boot_delay= Documentation: userspace-api: correct spelling Documentation: sparc: correct spelling Documentation: driver-api: correct spelling Documentation: admin-guide: correct spelling docs: add workload-tracing document to admin-guide docs/admin-guide/mm: remove useless markup docs/mm: remove useless markup docs/mm: Physical Memory: remove useless markup docs/sp_SP: Add process magic-number translation docs: ftrace: always use canonical ftrace path Doc/damon: fix the data path error dma-buf: Add "dma-buf" to title of documentation ...

docs: Add more information to the HTML sidebar

2023-02-08T20:28:27+00:00

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 Reviewed-by: David Gow

bpf: Document usage of the new __bpf_kfunc macro

2023-02-01T23:25:14+00:00

Now that the __bpf_kfunc macro has been added to linux/btf.h, include a blurb about it in the kfuncs.rst file. In order for the macro to successfully render with .. kernel-doc, we'll also need to add it to the c_id_attributes array. Signed-off-by: David Vernet Signed-off-by: Daniel Borkmann Acked-by: Stanislav Fomichev Link: https://lore.kernel.org/bpf/20230201173016.342758-3-void@manifault.com

docs/conf.py: Use about.html only in sidebar of alabaster theme

2023-01-11T22:06:50+00:00

"about.html" is available only for the alabaster theme [1]. Unconditionally putting it to html_sidebars prevents us from using other themes which respect html_sidebars. Remove about.html from the initialization and insert it at the front for the alabaster theme. Link: [1] https://alabaster.readthedocs.io/en/latest/installation.html#sidebars Fixes: d5389d3145ef ("docs: Switch the default HTML theme to alabaster") Signed-off-by: Akira Yokosawa Cc: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/4b162dbe-2a7f-1710-93e0-754cf8680aae@gmail.com Signed-off-by: Jonathan Corbet

docs: Deprecate use of Sphinx < 2.4.x

2023-01-06T20:04:15+00:00

The Sphinx 2.4 release is three years old, and it is becoming increasingly difficult to even find a system with an sufficiently archaic Python installation that can run versions older than that. I can no longer test changes against anything prior to 2.4.x. Move toward raising our minimum Sphinx requirement to 2.4.x so we can delete some older support code and claim to support a range of versions that we can actually test. In the absence of screams, the actual removal of support can happen later in 2023. Signed-off-by: Jonathan Corbet

docs/sphinx: More depth in the rtd sidebar toc

2022-11-09T20:28:40+00:00

We love to nest our documenation for good structure, but that means the table of contents needs to keep up or you can't navigate them. Realized this trying to find the drm property documentation, which with some shuffling around disappeared. Why I didn't realize we can do this earlier, no idea. Since the relevant parts of the toc are only loaded if you're in the right .html file there's no harm in going all the way to unlimited. Note that this has no impact on the alabaster theme (which has a much simpler sidebar toc which doesn't show the entire hierarchy, only what's in the local rendered file) nor on the various :toctree: rendered inline in the output. Signed-off-by: Daniel Vetter Cc: Jonathan Corbet Cc: linux-doc@vger.kernel.org Link: https://lore.kernel.org/r/20221108115707.1232621-1-daniel.vetter@ffwll.ch Signed-off-by: Jonathan Corbet