Re: [PATCH v2] docs: Raise the minimum Sphinx requirement to 2.4.4

From: Akira Yokosawa <akiyks@gmail.com>
To: Jonathan Corbet <corbet@lwn.net>, linux-doc@vger.kernel.org
Cc: linux-kernel@vger.kernel.org,
	Mauro Carvalho Chehab <mchehab@kernel.org>,
	Akira Yokosawa <akiyks@gmail.com>
Subject: Re: [PATCH v2] docs: Raise the minimum Sphinx requirement to 2.4.4
Date: Sun, 10 Dec 2023 08:44:33 +0900	[thread overview]
Message-ID: <50830030-dca7-4c43-bcc8-449c7cfa9fbb@gmail.com> (raw)
In-Reply-To: <874jgs47fq.fsf@meer.lwn.net>

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@kernel.org>
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
> ---
> 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@gmail.com>
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@gmail.com>
---
 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

