linux-stable.git/Documentation/sphinx, branch v6.9

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

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

2024-02-08T18:05:35+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

docs/sphinx: Fix TOC scroll hack for the home page

2024-01-23T21:33:13+00:00

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 
Signed-off-by: Jonathan Corbet 
Link: https://lore.kernel.org/r/20240123162157.61819-2-gustavo.sousa@intel.com

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

2024-01-17T19:49:11+00:00

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

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

2024-01-12T03:46:52+00:00

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