linux.git/Documentation/sphinx, branch v6.12.80

docs: kdoc: handle the obsolescensce of docutils.ErrorString()

2025-11-02T13:15:22+00:00

commit 00d95fcc4dee66dfb6980de6f2973b32f973a1eb upstream.

The ErrorString() and SafeString() docutils functions were helpers meant to
ease the handling of encodings during the Python 3 transition.  There is no
real need for them after Python 3.6, and docutils 0.22 removes them,
breaking the docs build

Handle this by just injecting our own one-liner version of ErrorString(),
and removing the sole SafeString() call entirely.

Reported-by: Zhixu Liu 
Signed-off-by: Jonathan Corbet 
Message-ID: <87ldmnv2pi.fsf@trenco.lwn.net>
[ Salvatore Bonaccorso: Backport to v6.17.y for context changes in
  Documentation/sphinx/kernel_include.py with major refactorings for the v6.18
  development cycle. Backport ErrorString definition as well to
  Documentation/sphinx/kernel_abi.py file for 6.12.y where it is imported
  from docutils before the faccc0ec64e1 ("docs: sphinx/kernel_abi: adjust
  coding style") change. ]
Suggested-by: Andreas Radke 
Signed-off-by: Salvatore Bonaccorso 
Signed-off-by: Greg Kroah-Hartman

docs: kerneldoc-preamble.sty: Suppress extra spaces in CJK literal blocks

2024-09-05T20:16:41+00:00

In zh_CN part of translations.pdf, there are several ASCII-art
diagrams whose vertical lines look sometimes jagged.
This is due to the interference between default settings of xeCJK
and fancyvrb (employed in sphinxVerbatim env), where extra space
is inserted between a latin char and a non-latin char when they
are next to each other (i.e., no explicit white space).

This issue can be suppressed by invoking \CJKsetecglue{} at the
beginning of every sphinxVerbatim enviornment.

\AtBeginEnvironment, provided by the etoolbox package, is useful in
this case.

Signed-off-by: Akira Yokosawa 
Signed-off-by: Jonathan Corbet 
Link: https://lore.kernel.org/r/20240905050941.31439-1-akiyks@gmail.com

docs: kernel_include.py: Cope with docutils 0.21

2024-05-02T15:50:59+00:00

Running "make htmldocs" on a newly installed Sphinx 7.3.7 ends up in
a build error:

    Sphinx parallel build error:
    AttributeError: module 'docutils.nodes' has no attribute 'reprunicode'

docutils 0.21 has removed nodes.reprunicode, quote from release note [1]:

  * Removed objects:

    docutils.nodes.reprunicode, docutils.nodes.ensure_str()
        Python 2 compatibility hacks

Sphinx 7.3.0 supports docutils 0.21 [2]:

kernel_include.py, whose origin is misc.py of docutils, uses reprunicode.

Upstream docutils removed the offending line from the corresponding file
(docutils/docutils/parsers/rst/directives/misc.py) in January 2022.
Quoting the changelog [3]:

    Deprecate `nodes.reprunicode` and `nodes.ensure_str()`.

    Drop uses of the deprecated constructs (not required with Python 3).

Do the same for kernel_include.py.

Tested against:
  - Sphinx 2.4.5 (docutils 0.17.1)
  - Sphinx 3.4.3 (docutils 0.17.1)
  - Sphinx 5.3.0 (docutils 0.18.1)
  - Sphinx 6.2.1 (docutils 0.19)
  - Sphinx 7.2.6 (docutils 0.20.1)
  - Sphinx 7.3.7 (docutils 0.21.2)

Link: http://www.docutils.org/RELEASE-NOTES.html#release-0-21-2024-04-09 [1]
Link: https://www.sphinx-doc.org/en/master/changes.html#release-7-3-0-released-apr-16-2024 [2]
Link: https://github.com/docutils/docutils/commit/c8471ce47a24 [3]
Signed-off-by: Akira Yokosawa 
Cc: stable@vger.kernel.org
Signed-off-by: Jonathan Corbet 
Link: https://lore.kernel.org/r/faf5fa45-2a9d-4573-9d2e-3930bdc1ed65@gmail.com

docs: Detect variable fonts and suggest denylisting them

2024-04-10T20:10:13+00:00

Fedora and openSUSE has started deploying "variable font" [1] format
Noto CJK fonts [2, 3].  "CJK" here stands for "Chinese, Japanese,
and Korean".

Unfortunately, XeTeX/XeLaTeX doesn't understand those fonts for
historical reasons and builds of translations.pdf end up in errors
if such fonts are present on the build host.

To help developers work around the issue, add a script to check the
presence of "variable font" Noto CJK fonts and to emit suggestions.
The script is invoked in the error path of "make pdfdocs" so that the
suggestions are made only when a PDF build actually fails.

The first suggestion is to denylist those "variable font" files by
activating a per-user and command-local fontconfig setting.

For further info and backgrounds, please refer to the header comment
of scripts/check-variable-font.sh newly added in this commit.

Link: [1] https://en.wikipedia.org/wiki/Variable_font
Link: [2] https://fedoraproject.org/wiki/Changes/Noto_CJK_Variable_Fonts
Link: [3] https://build.opensuse.org/request/show/1157217
Reported-by: Jonathan Corbet 
Link: https://lore.kernel.org/r/8734tqsrt7.fsf@meer.lwn.net/
Reported-by: Иван Иванович 
Link: https://lore.kernel.org/linux-doc/1708585803.600323099@f111.i.mail.ru/
Cc: Randy Dunlap 
Signed-off-by: Akira Yokosawa 
Signed-off-by: Jonathan Corbet 
Link: https://lore.kernel.org/r/20240406020416.25096-1-akiyks@gmail.com

docs: drop the version constraints for sphinx and dependencies

2024-03-03T15:17:20+00:00

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 
Tested-by: Vegard Nossum 
Signed-off-by: Lukas Bulwahn 
Signed-off-by: Jonathan Corbet 
Message-ID: <20240301141800.30218-1-lukas.bulwahn@gmail.com>

docs: kerneldoc-preamble.sty: Remove code for Sphinx <2.4

2024-03-03T15:15:22+00:00

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 
Signed-off-by: Jonathan Corbet 
Message-ID:

Merge branch 'docs-fixes' into docs-mw

2024-02-21T20:46:25+00:00

Bring in the build fixes so that we can successfully build PDFs again.

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

2024-02-21T20:44:21+00:00

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

doc: kerneldoc.py: fix indentation

2024-02-21T20:44:21+00:00

kerneldoc.py is mostly indented with 4 spaces (like PEP8 suggests);
replace the last remaining tabs for consistency.

No functional change.

Cc: Jani Nikula 
Cc: Mauro Carvalho Chehab 
Signed-off-by: Vegard Nossum 
Reviewed-by: Randy Dunlap 
Signed-off-by: Jonathan Corbet 
Link: https://lore.kernel.org/r/20240215134828.1277109-6-vegard.nossum@oracle.com

docs: translations: use attribute to store current language

2024-02-21T20:41:37+00:00

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