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 <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
---
Only change since v1 is setting the recommended version to 3.4.3, as
seems to be the consensus for the best choice.
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(-)
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 20bd74edcca9..3a1a804c3a13 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -47,7 +47,7 @@ from load_config import loadConfig
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
-needs_sphinx = '1.7'
+needs_sphinx = '2.4.4'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
index bb7971643fcf..3d125fb4139d 100644
--- a/Documentation/doc-guide/sphinx.rst
+++ b/Documentation/doc-guide/sphinx.rst
@@ -28,7 +28,7 @@ Sphinx Install
==============
The ReST markups currently used by the Documentation/ files are meant to be
-built with ``Sphinx`` version 1.7 or higher.
+built with ``Sphinx`` version 2.4.4 or higher.
There's a script that checks for the Sphinx requirements. Please see
:ref:`sphinx-pre-install` for further details.
diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst
index bb96ca0f774b..559587a89974 100644
--- a/Documentation/process/changes.rst
+++ b/Documentation/process/changes.rst
@@ -58,7 +58,7 @@ mcelog 0.6 mcelog --version
iptables 1.4.2 iptables -V
openssl & libcrypto 1.0.0 openssl version
bc 1.06.95 bc --version
-Sphinx\ [#f1]_ 1.7 sphinx-build --version
+Sphinx\ [#f1]_ 2.4.4 sphinx-build --version
cpio any cpio --version
GNU tar 1.28 tar --version
gtags (optional) 6.6.5 gtags --version
diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py
index acc6d55718bd..a413f8dd5115 100644
--- a/Documentation/sphinx/automarkup.py
+++ b/Documentation/sphinx/automarkup.py
@@ -7,11 +7,7 @@
from docutils import nodes
import sphinx
from sphinx import addnodes
-if sphinx.version_info[0] < 2 or \
- sphinx.version_info[0] == 2 and sphinx.version_info[1] < 1:
- from sphinx.environment import NoUri
-else:
- from sphinx.errors import NoUri
+from sphinx.errors import NoUri
import re
from itertools import chain
diff --git a/Documentation/sphinx/cdomain.py b/Documentation/sphinx/cdomain.py
index 4eb150bf509c..e6959af25402 100644
--- a/Documentation/sphinx/cdomain.py
+++ b/Documentation/sphinx/cdomain.py
@@ -127,11 +127,7 @@ def setup(app):
# Handle easy Sphinx 3.1+ simple new tags: :c:expr and .. c:namespace::
app.connect('source-read', c_markups)
-
- if (major == 1 and minor < 8):
- app.override_domain(CDomain)
- else:
- app.add_domain(CDomain, override=True)
+ app.add_domain(CDomain, override=True)
return dict(
version = __version__,
diff --git a/Documentation/sphinx/kfigure.py b/Documentation/sphinx/kfigure.py
index 13e885bbd499..97166333b727 100644
--- a/Documentation/sphinx/kfigure.py
+++ b/Documentation/sphinx/kfigure.py
@@ -61,13 +61,7 @@ import sphinx
from sphinx.util.nodes import clean_astext
import kernellog
-# Get Sphinx version
-major, minor, patch = sphinx.version_info[:3]
-if major == 1 and minor > 3:
- # patches.Figure only landed in Sphinx 1.4
- from sphinx.directives.patches import Figure # pylint: disable=C0413
-else:
- Figure = images.Figure
+Figure = images.Figure
__version__ = '1.0.0'
diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install
index 1fb88fdceec3..25aefbb35377 100755
--- a/scripts/sphinx-pre-install
+++ b/scripts/sphinx-pre-install
@@ -32,8 +32,7 @@ my $python_cmd = "";
my $activate_cmd;
my $min_version;
my $cur_version;
-my $rec_version = "1.7.9"; # PDF won't build here
-my $min_pdf_version = "2.4.4"; # Min version where pdf builds
+my $rec_version = "3.4.3";
my $latest_avail_ver;
#
@@ -791,9 +790,6 @@ sub recommend_sphinx_version($)
# Version is OK. Nothing to do.
if ($cur_version && ($cur_version ge $rec_version)) {
- if ($cur_version lt $min_pdf_version) {
- print "note: If you want pdf, you need at least Sphinx $min_pdf_version.\n";
- }
return;
};
@@ -842,10 +838,6 @@ sub recommend_sphinx_version($)
printf "\t. $activate_cmd\n";
deactivate_help();
- if ($latest_avail_ver lt $min_pdf_version) {
- print "note: If you want pdf, you need at least Sphinx $min_pdf_version.\n";
- }
-
return;
}
--
2.42.0
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 <[email protected]>
> Signed-off-by: Jonathan Corbet <[email protected]>
> ---
> 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 <[email protected]>
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 <[email protected]>
---
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
Hi Akira,
kernel test robot noticed the following build warnings:
[auto build test WARNING on lwn/docs-next]
[also build test WARNING on linus/master v6.7-rc5 next-20231211]
[If your patch is applied to the wrong git tree, kindly drop us a note.
And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch#_base_tree_information]
url: https://github.com/intel-lab-lkp/linux/commits/Akira-Yokosawa/docs-sphinx-requirement-txt-Reflect-recommended-Sphinx-version/20231210-074628
base: git://git.lwn.net/linux.git docs-next
patch link: https://lore.kernel.org/r/50830030-dca7-4c43-bcc8-449c7cfa9fbb%40gmail.com
patch subject: [PATCH] docs: sphinx/requirement.txt: Reflect recommended Sphinx version
reproduce: (https://download.01.org/0day-ci/archive/20231212/[email protected]/reproduce)
If you fix the issue in a separate patch/commit (i.e. not just a new version of
the same patch/commit), kindly add following tags
| Reported-by: kernel test robot <[email protected]>
| Closes: https://lore.kernel.org/oe-kbuild-all/[email protected]/
All warnings (new ones prefixed by >>):
>> Documentation/gpu/drm-kms:360: ./drivers/gpu/drm/drm_fourcc.c:344: WARNING: Duplicate C declaration, also defined at gpu/drm-kms:39.
>> Documentation/gpu/drm-kms:461: ./drivers/gpu/drm/drm_modeset_lock.c:392: WARNING: Duplicate C declaration, also defined at gpu/drm-kms:49.
>> Documentation/gpu/drm-uapi:434: ./drivers/gpu/drm/drm_ioctl.c:928: WARNING: Duplicate C declaration, also defined at gpu/drm-uapi:70.
--
0-DAY CI Kernel Test Service
https://github.com/intel/lkp-tests/wiki
On 2023/12/12 8:27, kernel test robot wrote:
> Hi Akira,
>
> kernel test robot noticed the following build warnings:
>
> [auto build test WARNING on lwn/docs-next]
> [also build test WARNING on linus/master v6.7-rc5 next-20231211]
> [If your patch is applied to the wrong git tree, kindly drop us a note.
> And when submitting patch, we suggest to use '--base' as documented in
> https://git-scm.com/docs/git-format-patch#_base_tree_information]
>
> url: https://github.com/intel-lab-lkp/linux/commits/Akira-Yokosawa/docs-sphinx-requirement-txt-Reflect-recommended-Sphinx-version/20231210-074628
> base: git://git.lwn.net/linux.git docs-next
> patch link: https://lore.kernel.org/r/50830030-dca7-4c43-bcc8-449c7cfa9fbb%40gmail.com
> patch subject: [PATCH] docs: sphinx/requirement.txt: Reflect recommended Sphinx version
> reproduce: (https://download.01.org/0day-ci/archive/20231212/[email protected]/reproduce)
>
> If you fix the issue in a separate patch/commit (i.e. not just a new version of
> the same patch/commit), kindly add following tags
> | Reported-by: kernel test robot <[email protected]>
> | Closes: https://lore.kernel.org/oe-kbuild-all/[email protected]/
>
> All warnings (new ones prefixed by >>):
>
>>> Documentation/gpu/drm-kms:360: ./drivers/gpu/drm/drm_fourcc.c:344: WARNING: Duplicate C declaration, also defined at gpu/drm-kms:39.
>>> Documentation/gpu/drm-kms:461: ./drivers/gpu/drm/drm_modeset_lock.c:392: WARNING: Duplicate C declaration, also defined at gpu/drm-kms:49.
>>> Documentation/gpu/drm-uapi:434: ./drivers/gpu/drm/drm_ioctl.c:928: WARNING: Duplicate C declaration, also defined at gpu/drm-uapi:70.
>
These warnings on duplicate C decl are expected when you upgrade
Sphinx to >= 3.1.
See https://github.com/sphinx-doc/sphinx/issues/7819 for the long
standing bug of Sphinx.
Anyway, I can't do anything in response to this report.
Regards,
Akira
Akira Yokosawa <[email protected]> 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 <[email protected]>
> 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 <[email protected]>
> ---
> 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
Hi,
On Fri, 15 Dec 2023 08:36:06 -0700, Jonathan Corbet wrote:
> Akira Yokosawa <[email protected]> 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 <[email protected]>
>> 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 <[email protected]>
>> ---
>> 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