Received-SPF: pass (google.com: domain of linux-kernel+bounces-1226-linux.lists.archive=gmail.com@vger.kernel.org designates 147.75.80.249 as permitted sender) client-ip=147.75.80.249;
From: Jonathan Corbet <corbet@lwn.net>
To: Akira Yokosawa <akiyks@gmail.com>, 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
In-Reply-To: <50830030-dca7-4c43-bcc8-449c7cfa9fbb@gmail.com>
References: <874jgs47fq.fsf@meer.lwn.net>
 <50830030-dca7-4c43-bcc8-449c7cfa9fbb@gmail.com>
Date: Fri, 15 Dec 2023 08:36:06 -0700
Message-ID: <87sf43qxzt.fsf@meer.lwn.net>
Precedence: bulk
MIME-Version: 1.0
Content-Type: text/plain

Akira Yokosawa <akiyks@gmail.com> writes:

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

So I can apply this, certainly, but it makes me feel like perhaps we
need to reconsider our approach a bit.  It's kind of weird that we have
a minimum supported version, then a semi-random "recommended" version
that is still pretty old.

Is there a reason to suggest to people that they should run something
other than current sphinx, especially if they are updating it anyway?
So our "recommended version" is really "recommended *minimum* version"? 


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

Here we could take version numbers out entirely; otherwise we'll always
be updating this.

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

I'd forgotten about the docutils fun.  I wonder of our recommended
minimum should actually be 4.0, then here we could put simply:

  Sphinx>4.0

?

Thanks,

jon