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

[Akira Yokosawa]

Hi,

On Fri, 15 Dec 2023 08:36:06 -0700, Jonathan Corbet wrote:
> Akira Yokosawa <akiyks@xxxxxxxxx> 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"?

I picked 3.4.3 just because it is the version of distro Sphinx on
debian 11 and RHEL 9.  It works just fine and "make htmldocs" should
not complain it as not-recommended.

In sphinx-pre-install, "recommended version", aka $rec_version, works
as a criteria to emit upgrade suggestion.

That said, I think it should be OK if "pip install -r requirements.txt"
installs a newer version.

>
> 
>> ----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
> 
> Here we could take version numbers out entirely; otherwise we'll always
> be updating this.

I thing this should be a verbatim copy of message from sphinx_pre_install
presented later in sphinx.rst.

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

I tried it and "make htmldocs" complains:

    Can't get default sphinx version from ./Documentation/sphinx/requirements.txt at ./scripts/sphinx-pre-install line 305.
    make[2]: *** [Documentation/Makefile:101: htmldocs] Error 255
    make[1]: *** [/home/akira/git/linux/Makefile:1695: htmldocs] Error 2
    make: *** [Makefile:234: __sub-make] Error 2

I did try to remedy this, but realized that I was too frustrated in
deciphering the script to come up with a reasonable update.

I'm giving up on this.

Sorry about that.

Regards,
Akira

> 
> ?
> 
> Thanks,
> 
> jon