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.
Cc: Mauro Carvalho Chehab <[email protected]>
Cc: Akira Yokosawa <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
---
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..db75b1b86086 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.0";
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
Em Mon, 27 Nov 2023 16:31:39 -0700
Jonathan Corbet <[email protected]> escreveu:
> 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.
>
> Cc: Mauro Carvalho Chehab <[email protected]>
> Cc: Akira Yokosawa <[email protected]>
> Signed-off-by: Jonathan Corbet <[email protected]>
> ---
> 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..db75b1b86086 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.0";
Please don't. 3.0 version has a broken C domain, not properly supported.
The fixes arrived only starting at 3.1 (I guess some went to 3.2, but
3.1 is usable, as far as I remember).
With such change, feel free to add:
Reviewed-by: Mauro Carvalho Chehab <[email protected]>
> 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;
> }
>
Thanks,
Mauro
Mauro Carvalho Chehab <[email protected]> writes:
> Em Mon, 27 Nov 2023 16:31:39 -0700
> Jonathan Corbet <[email protected]> escreveu:
>> diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install
>> index 1fb88fdceec3..db75b1b86086 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.0";
>
> Please don't. 3.0 version has a broken C domain, not properly supported.
> The fixes arrived only starting at 3.1 (I guess some went to 3.2, but
> 3.1 is usable, as far as I remember).
So you're asking for 3.1 or 3.2 instead of 3.0?
Honestly, I just picked 3.0 out of the air in the hopes of eventually
deprecating 2.x. Not lots of thought has gone into that
number...perhaps we should recommend higher yet?
Thanks,
jon
Em Tue, 28 Nov 2023 07:42:12 -0700
Jonathan Corbet <[email protected]> escreveu:
> Mauro Carvalho Chehab <[email protected]> writes:
>
> > Em Mon, 27 Nov 2023 16:31:39 -0700
> > Jonathan Corbet <[email protected]> escreveu:
>
> >> diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install
> >> index 1fb88fdceec3..db75b1b86086 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.0";
> >
> > Please don't. 3.0 version has a broken C domain, not properly supported.
> > The fixes arrived only starting at 3.1 (I guess some went to 3.2, but
> > 3.1 is usable, as far as I remember).
>
> So you're asking for 3.1 or 3.2 instead of 3.0?
Yes.
>
> Honestly, I just picked 3.0 out of the air in the hopes of eventually
> deprecating 2.x. Not lots of thought has gone into that
> number...perhaps we should recommend higher yet?
Well, we could recommend a higher version, but I can't see much
differences between 3.2 and the latest version: for what we use,
both will work on a similar way. Ok, layout may be different, there
were some improvements on PDF output, etc. but they will all produce
a decent documentation.
Yet, while most C domain bugs introduced on 3.0 were solved in 3.1
and 3.2, there's one still pending issue[1].
Once C domain finally gets rid from this long term bug that having:
.. c:struct:: foo
.. c:function:: void foo(void)
Produce warnings that "foo" id duplicated, then we'll have, IMO,
our next recommended version :-)
While Sphinx developers don't fix such bug, it doesn't really matter
what version user will pick, so I would just pick the fastest one
as a recommendation, starting from 3.1 or 3.2 as our currently
recommended version.
[1] https://github.com/sphinx-doc/sphinx/pull/8313
While I didn't make any benchmarks, I remember people reported
poor performance with newer versions, so, without thinking to
much, 3.1 or 3.2 seems a good candidate for the recommended
version.
Regards,
Mauro
Hi,
On 2023/11/29 0:56, Mauro Carvalho Chehab wrote:
[snip]
> While I didn't make any benchmarks, I remember people reported
> poor performance with newer versions, so, without thinking to
> much, 3.1 or 3.2 seems a good candidate for the recommended
> version.
Well, I have different impressions on the performance of Sphinx >=3.1
and have done some quick benchmarks.
Here are results on a not-so-performant machine.
Benchmark of building htmldocs on Ubuntu 22.04 (after "make cleandocs"):
Sphinx elapesed maxresident (k)
======== ========== ===============
2.4.5 7m44.57 2806152 (parallel slot = 3)
3.1.2 11m25.28 1036264 (parallel slot = 4)
3.4.3 10m22.26 1067100 (ditto.)
4.2.0 10m16.53 1151220
4.3.2 10m06.07 1123432 (distro pkg of Ubuntu 22.04LTS)
5.3.0 10m18.73 1145524
7.2.6 9m53.80 1261736
python3: Python 3.10.12
Sidenotes:
1: Sphinx 4.3.0 officially added Python 3.10 support.
Sphinx 4.2.0 also works with Python 3.10.
Sphinx <3.5.0 happen to work with Python 3.10.
2: Sphinx 7.2.0 obsoleted Python 3.8.
3: Sphinx 6.0.0 obsoleted Python 3.6 and 3.7.
And here is a table of distro Sphinx packages:
As of 2023.11.30
----------------------------------
Distro Sphinx Python3
=================== ====== =======
Ubuntu 22.04 LTS 4.3.2 3.10.12
Debian 11 3.4.3 3.9.2
Debian 12 5.3.0 3.11.2
Fedora 39 6.2.1 3.12.0
RHEL 9 3.4.3 3.9.18
Mageia 9 6.1.3 3.10.11
openSUSE Leap 15.5 4.2.0 3.6.15 (provided as python3-Sphinx_4_2_0)
----------------------------------
So, I think Sphinx 3.4.3 would be a reasonable choice for
recommending.
HTH,
Akira
>
> Regards,
> Mauro
Em Thu, 30 Nov 2023 16:33:56 +0900
Akira Yokosawa <[email protected]> escreveu:
> Hi,
>
> On 2023/11/29 0:56, Mauro Carvalho Chehab wrote:
> [snip]
>
> > While I didn't make any benchmarks, I remember people reported
> > poor performance with newer versions, so, without thinking to
> > much, 3.1 or 3.2 seems a good candidate for the recommended
> > version.
>
> Well, I have different impressions on the performance of Sphinx >=3.1
> and have done some quick benchmarks.
> Here are results on a not-so-performant machine.
>
> Benchmark of building htmldocs on Ubuntu 22.04 (after "make cleandocs"):
>
> Sphinx elapesed maxresident (k)
> ======== ========== ===============
> 2.4.5 7m44.57 2806152 (parallel slot = 3)
> 3.1.2 11m25.28 1036264 (parallel slot = 4)
> 3.4.3 10m22.26 1067100 (ditto.)
> 4.2.0 10m16.53 1151220
> 4.3.2 10m06.07 1123432 (distro pkg of Ubuntu 22.04LTS)
> 5.3.0 10m18.73 1145524
> 7.2.6 9m53.80 1261736
>
> python3: Python 3.10.12
>
> Sidenotes:
>
> 1: Sphinx 4.3.0 officially added Python 3.10 support.
> Sphinx 4.2.0 also works with Python 3.10.
> Sphinx <3.5.0 happen to work with Python 3.10.
> 2: Sphinx 7.2.0 obsoleted Python 3.8.
> 3: Sphinx 6.0.0 obsoleted Python 3.6 and 3.7.
>
>
> And here is a table of distro Sphinx packages:
>
> As of 2023.11.30
>
> ----------------------------------
> Distro Sphinx Python3
> =================== ====== =======
> Ubuntu 22.04 LTS 4.3.2 3.10.12
> Debian 11 3.4.3 3.9.2
> Debian 12 5.3.0 3.11.2
> Fedora 39 6.2.1 3.12.0
> RHEL 9 3.4.3 3.9.18
> Mageia 9 6.1.3 3.10.11
> openSUSE Leap 15.5 4.2.0 3.6.15 (provided as python3-Sphinx_4_2_0)
> ----------------------------------
>
> So, I think Sphinx 3.4.3 would be a reasonable choice for
> recommending.
Works for me.
Regards,
Mauro