Hi,
On Fri, 08 Dec 2023 16:10:17 -0700, Jonathan Corbet wrote:
> 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 <mchehab@xxxxxxxxxx>
> Signed-off-by: Jonathan Corbet <corbet@xxxxxxx>
> ---
> Only change since v1 is setting the recommended version to 3.4.3, as
> seems to be the consensus for the best choice.
With this patch applied, I get a confusing looking warning from
"make htmldocs" on a machine where the Sphinx version is 2.4.5:
--------
Warning: It is recommended at least Sphinx version 3.4.3.
To upgrade Sphinx, use:
/home/akira/sphinx-2.4.5/bin/python3 -m venv sphinx_2.4.4
. sphinx_2.4.4/bin/activate
pip install -r ./Documentation/sphinx/requirements.txt
If you want to exit the virtualenv, you can use:
deactivate
--------
Looks like we need to update requirements.txt as well so that it
installs Sphinx 3.4.3. Appended below is a fixup patch to that
effect.
Thanks, Akira
>
> Documentation/conf.py | 2 +-
> Documentation/doc-guide/sphinx.rst | 2 +-
> Documentation/process/changes.rst | 2 +-
> Documentation/sphinx/automarkup.py | 6 +-----
> Documentation/sphinx/cdomain.py | 6 +-----
> Documentation/sphinx/kfigure.py | 8 +-------
> scripts/sphinx-pre-install | 10 +---------
> 7 files changed, 7 insertions(+), 29 deletions(-)
>
[...]
----8<----
From: Akira Yokosawa <akiyks@xxxxxxxxx>
Subject: [PATCH] docs: sphinx/requirement.txt: Reflect recommended Sphinx version
sphinx_pre_install parses the version of Sphinx in requirements.txt
and emits messages based on it.
Update requirements.txt so that it installs Sphinx 3.4.3, as well as
the examples in documentation.
Signed-off-by: Akira Yokosawa <akiyks@xxxxxxxxx>
---
Documentation/doc-guide/sphinx.rst | 14 +++++++-------
Documentation/sphinx/requirements.txt | 4 +++-
2 files changed, 10 insertions(+), 8 deletions(-)
diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
index 3d125fb4139d..5227a2611026 100644
--- a/Documentation/doc-guide/sphinx.rst
+++ b/Documentation/doc-guide/sphinx.rst
@@ -48,13 +48,13 @@ or ``virtualenv``, depending on how your distribution packaged Python 3.
on the Sphinx version, it should be installed separately,
with ``pip install sphinx_rtd_theme``.
-In summary, if you want to install Sphinx version 2.4.4, you should do::
+In summary, if you want to install Sphinx version 3.4.3, you should do::
- $ virtualenv sphinx_2.4.4
- $ . sphinx_2.4.4/bin/activate
- (sphinx_2.4.4) $ pip install -r Documentation/sphinx/requirements.txt
+ $ virtualenv sphinx_3.4.3
+ $ . sphinx_3.4.3/bin/activate
+ (sphinx_3.4.3) $ pip install -r Documentation/sphinx/requirements.txt
-After running ``. sphinx_2.4.4/bin/activate``, the prompt will change,
+After running ``. sphinx_3.4.3/bin/activate``, the prompt will change,
in order to indicate that you're using the new environment. If you
open a new shell, you need to rerun this command to enter again at
the virtual environment before building the documentation.
@@ -118,8 +118,8 @@ command line options for your distro::
You should run:
sudo dnf install -y texlive-luatex85
- /usr/bin/virtualenv sphinx_2.4.4
- . sphinx_2.4.4/bin/activate
+ /usr/bin/virtualenv sphinx_3.4.3
+ . sphinx_3.4.3/bin/activate
pip install -r Documentation/sphinx/requirements.txt
Can't build as 1 mandatory dependency is missing at ./scripts/sphinx-pre-install line 468.
diff --git a/Documentation/sphinx/requirements.txt b/Documentation/sphinx/requirements.txt
index 335b53df35e2..89329e67e788 100644
--- a/Documentation/sphinx/requirements.txt
+++ b/Documentation/sphinx/requirements.txt
@@ -1,3 +1,5 @@
# jinja2>=3.1 is not compatible with Sphinx<4.0
jinja2<3.1
-Sphinx==2.4.4
+# docutils>=0.18 is not compatible with 3.0 <= Sphinx < 4.0
+docutils<0.18
+Sphinx==3.4.3
--
2.34.1
