linux.git/Documentation/conf.py, branch v6.17

docs: conf.py: several coding style fixes

2025-06-25T18:22:48+00:00

conf.py is missing a SPDX header and doesn't really have
a proper python coding style. It also has an obsolete
commented LaTeX syntax that doesn't work anymore.

Clean it up a little bit with some help from autolints
and manual adjustments.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet 
Link: https://lore.kernel.org/r/063c106d96e86ca30c3266f7819f30b7247881ed.1750571906.git.mchehab+huawei@kernel.org

docs: conf.py: properly handle include and exclude patterns

2025-06-25T18:22:47+00:00

When one does:
	make SPHINXDIRS="foo" htmldocs

All patterns would be relative to Documentation/foo, which
causes the include/exclude patterns like:

	include_patterns = [
		...
		f'foo/*.{ext}',
	]

to break. This is not what it is expected. Address it by
adding a logic to dynamically adjust the pattern when
SPHINXDIRS is used.

That allows adding parsers for other file types.

It should be noticed that include_patterns was added on
Sphinx 5.1:
	https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-include_patterns

So, a backward-compatible code is needed when we start
using it for real.

Signed-off-by: Mauro Carvalho Chehab 
Reviewed-by: Donald Hunter 
Signed-off-by: Jonathan Corbet 
Link: https://lore.kernel.org/r/429c9c670fe27860f5e4f29aaf72576a4ed52ad1.1750571906.git.mchehab+huawei@kernel.org

docs: conf.py: drop backward support for old Sphinx versions

2025-05-19T14:02:14+00:00

Since commit 5e25b972a22b ("docs: changes: update Python minimal version"),
the minimal Sphinx version is 3.4.3.

Drop support for older versions from the config file.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet 
Message-ID: <20250507121117.317810-1-mchehab+huawei@kernel.org>

docs: sphinx: kerneldoc: use kernel-doc.py script

2025-04-09T18:10:34+00:00

Switch to the new version when producing documentation.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet 
Link: https://lore.kernel.org/r/a81d8db099d9cef5161deaef40ac9056bf9802a3.1744106242.git.mchehab+huawei@kernel.org

docs: changes: update Sphinx minimal version to 3.4.3

2025-02-13T18:33:32+00:00

Doing that allows us to get rid of all backward-compatible code.

Signed-off-by: Mauro Carvalho Chehab 
Reviewed-by: Kees Cook 
Signed-off-by: Jonathan Corbet 
Link: https://lore.kernel.org/r/d79e357468c20d86913e9e343d785398f728aabb.1739254187.git.mchehab+huawei@kernel.org

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