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

compiler_types: add Endianness-dependent __counted_by_{le,be}

2024-03-29T01:50:47+00:00

Some structures contain flexible arrays at the end and the counter for them, but the counter has explicit Endianness and thus __counted_by() can't be used directly. To increase test coverage for potential problems without breaking anything, introduce __counted_by_{le,be}() defined depending on platform's Endianness to either __counted_by() when applicable or noop otherwise. Maybe it would be a good idea to introduce such attributes on compiler level if possible, but for now let's stop on what we have. Acked-by: Kees Cook Acked-by: Gustavo A. R. Silva Signed-off-by: Alexander Lobakin Reviewed-by: Przemek Kitszel Link: https://lore.kernel.org/r/20240327142241.1745989-2-aleksander.lobakin@intel.com Signed-off-by: Jakub Kicinski

docs: Restore "smart quotes" for quotes

2024-02-28T22:48:18+00:00

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

docs: Instruct LaTeX to cope with deeper nesting

2024-02-20T21:51:42+00:00

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

docs: translations: add translations links when they exist

2023-12-19T21:34:59+00:00

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

docs: conf.py: Ignore __counted_by attribute

2023-12-15T16:31:19+00:00

It seems that Sphinx is confused by the __counted_by attribute on struct members. Add it to the list of known attributes. Reported-by: kernel test robot Closes: https://lore.kernel.org/oe-kbuild-all/202312150614.kOx8xUkr-lkp@intel.com/ Cc: Jonathan Corbet Cc: "Gustavo A. R. Silva" Cc: linux-doc@vger.kernel.org Cc: linux-hardening@vger.kernel.org Signed-off-by: Kees Cook Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20231215001347.work.151-kees@kernel.org

docs: Raise the minimum Sphinx requirement to 2.4.4

2023-12-15T15:36:33+00:00

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 Link: https://lore.kernel.org/r/874jgs47fq.fsf@meer.lwn.net Signed-off-by: Jonathan Corbet

Documentation: add tux logo

2023-11-17T20:54:56+00:00

We already have the logo, let's use it. Testing: make htmldocs Cc: Miguel Ojeda Signed-off-by: Vegard Nossum Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20231029074207.297663-1-vegard.nossum@oracle.com

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 ...