kernel.git/Documentation/doc-guide/sphinx.rst, branch linux-rolling-lts

docs: sphinx: add a file with the requirements for lowest version

2025-06-25T18:22:48Z

Those days, it is hard to install a virtual env that would build docs with Sphinx 3.4.3, as even python 3.13 is not compatible anymore with it. /usr/bin/python3.9 -m venv sphinx_3.4.3 . sphinx_3.4.3/bin/activate pip install -r Documentation/sphinx/min_requirements.txt Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/e38a44ee64ebfa37eac5f64e47af51c7ac051d5a.1750571906.git.mchehab+huawei@kernel.org

Docs: doc-guide: update sphinx.rst Sphinx version number

2025-05-21T10:28:29Z

Update the minimum version number to match both Documentation/Changes and Documentation/conf.py. Signed-off-by: Randy Dunlap Cc: Jonathan Corbet Cc: linux-doc@vger.kernel.org Cc: Mauro Carvalho Chehab Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Message-ID: <20250519220413.2914890-1-rdunlap@infradead.org>

docs: doc-guide: clarify latest theme usage

2025-05-21T10:21:28Z

We have been using the Alabaster theme as the default theme since Sept. 2022. Keep the information on the RTD theme around in case someone wants to try it with the DOCS_THEME environment variable. Fixes: 26d797ffc1c0 ("docs: update sphinx.rst to reflect the default theme change") Signed-off-by: Randy Dunlap Cc: Jonathan Corbet Cc: linux-doc@vger.kernel.org Cc: Mauro Carvalho Chehab Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Message-ID: <20250519223613.37277-1-rdunlap@infradead.org>

docs: drop the version constraints for sphinx and dependencies

2024-03-03T15:17:20Z

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>

Documentation: multiple .rst files: Fix grammar and more consistent formatting

2024-02-05T17:24:54Z

sphinx.rst: - Remove unnecessary newline - Fix grammar s/on/in/ - Fix grammar s/check/checks/ - Capitalize heading "The C domain" changes.rst: - Remove colon after "pahole" to be consistent with other entries howto.rst: - Fix grammar s/you will/will you/ - Hyphenate "real-world problems" Signed-off-by: Thorsten Blum Reviewed-by: Randy Dunlap Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240205000117.3285-1-thorsten.blum@toblux.com

docs: Raise the minimum Sphinx requirement to 2.4.4

2023-12-15T15:36:33Z

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

docs: automarkup: linkify git revs

2023-11-17T20:13:24Z

There aren't a ton of references to commits in the documentation, but they do exist, and we can use automarkup to linkify them to make them easier to follow. Use something like this to find references to commits: git grep -P 'commit.*[0-9a-f]{8,}' Documentation/ Also fix a few of these to standardize on the exact format that is already used in changelogs. Signed-off-by: Vegard Nossum Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20231027115420.205279-1-vegard.nossum@oracle.com

docs/doc-guide: Clarify how to write tables

2023-06-09T07:57:56Z

Prior to this commit, the kernel docs writing guide spent over a page describing exactly how *not* to write tables into the kernel docs, without providing a example about the desired format. This patch provides a positive example first in the guide so that it's harder to miss, then leaves the existing less desirable approach below for contributors to follow if they have some stronger justification for why to use that approach. Signed-off-by: Joe Stringer Reviewed-by: Randy Dunlap Link: https://lore.kernel.org/r/20230424171850.3612317-1-joe@isovalent.com Signed-off-by: Jonathan Corbet

docs: update sphinx.rst to reflect the default theme change

2022-10-13T17:14:36Z

We don't default to Read The Docs anymore; update the docs to match. Acked-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet

docs/doc-guide: Add documentation on SPHINX_IMGMATH

2022-09-29T19:13:45Z

Now that building html docs with math expressions does not need texlive packages, remove the note on the requirement in the "Sphinx Install" section. Instead, add sections of "Math Expressions in HTML" and "Choice of Math Renderer". Describe the effect of setting SPHINX_IMGMATH in the latter section. Signed-off-by: Akira Yokosawa Cc: Mauro Carvalho Chehab Cc: Randy Dunlap Link: https://lore.kernel.org/r/a67e3279-6bc7-ee2c-2b49-9275252460b0@gmail.com Signed-off-by: Jonathan Corbet