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
