| Message ID | 20240702195903.204007-2-jsnow@redhat.com (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | docs/python: bump minimum Sphinx version | expand |
On 7/2/24 21:59, John Snow wrote: > With RHEL 8 support retired (It's been two years today since RHEL 9 > came out), our very oldest build platform version of Sphinx is now > 3.4.3; and keeping backwards compatibility for versions as old as v1.6 > when using domain extensions is a lot of work we don't need to do. Technically that's unrelated: thanks to your venv work, :) builds on RHEL 8 / CentOS Stream 8 do not pick the platform Sphinx, because it runs under Python 3.6. Therefore the version included in RHEL 8 does not matter for picking the minimum supported Sphinx version. > Debian 11: v3.4.3 (QEMU support ends 2024-07-xx) Nice. :) > diff --git a/pythondeps.toml b/pythondeps.toml > index 9c16602d303..bc656376caa 100644 > --- a/pythondeps.toml > +++ b/pythondeps.toml > @@ -23,7 +23,7 @@ meson = { accepted = ">=0.63.0", installed = "1.2.3", canary = "meson" } > > [docs] > # Please keep the installed versions in sync with docs/requirements.txt > -sphinx = { accepted = ">=1.6", installed = "5.3.0", canary = "sphinx-build" } > +sphinx = { accepted = ">=3.4.3", installed = "5.3.0", canary = "sphinx-build" } > sphinx_rtd_theme = { accepted = ">=0.5", installed = "1.1.1" } > > [avocado] Acked-by: Paolo Bonzini <pbonzini@redhat.com> Paolo
On Wed, Jul 3, 2024, 4:00 AM Paolo Bonzini <pbonzini@redhat.com> wrote: > On 7/2/24 21:59, John Snow wrote: > > With RHEL 8 support retired (It's been two years today since RHEL 9 > > came out), our very oldest build platform version of Sphinx is now > > 3.4.3; and keeping backwards compatibility for versions as old as v1.6 > > when using domain extensions is a lot of work we don't need to do. > > Technically that's unrelated: thanks to your venv work, :) builds on > RHEL 8 / CentOS Stream 8 do not pick the platform Sphinx, because it > runs under Python 3.6. Therefore the version included in RHEL 8 does > not matter for picking the minimum supported Sphinx version. > ...! I think I can't mandate 4.x because of RHEL 9 builds though, and offline requirements. > > Debian 11: v3.4.3 (QEMU support ends 2024-07-xx) > > Nice. :) > > > diff --git a/pythondeps.toml b/pythondeps.toml > > index 9c16602d303..bc656376caa 100644 > > --- a/pythondeps.toml > > +++ b/pythondeps.toml > > @@ -23,7 +23,7 @@ meson = { accepted = ">=0.63.0", installed = "1.2.3", > canary = "meson" } > > > > [docs] > > # Please keep the installed versions in sync with docs/requirements.txt > > -sphinx = { accepted = ">=1.6", installed = "5.3.0", canary = > "sphinx-build" } > > +sphinx = { accepted = ">=3.4.3", installed = "5.3.0", canary = > "sphinx-build" } > > sphinx_rtd_theme = { accepted = ">=0.5", installed = "1.1.1" } > > > > [avocado] > > Acked-by: Paolo Bonzini <pbonzini@redhat.com> > > Paolo > >
On Wed, Jul 3, 2024 at 2:06 PM John Snow <jsnow@redhat.com> wrote: > On Wed, Jul 3, 2024, 4:00 AM Paolo Bonzini <pbonzini@redhat.com> wrote: >> On 7/2/24 21:59, John Snow wrote: >> > With RHEL 8 support retired (It's been two years today since RHEL 9 >> > came out), our very oldest build platform version of Sphinx is now >> > 3.4.3; and keeping backwards compatibility for versions as old as v1.6 >> > when using domain extensions is a lot of work we don't need to do. >> >> Technically that's unrelated: thanks to your venv work, :) builds on >> RHEL 8 / CentOS Stream 8 do not pick the platform Sphinx, because it >> runs under Python 3.6. Therefore the version included in RHEL 8 does >> not matter for picking the minimum supported Sphinx version. > > I think I can't mandate 4.x because of RHEL 9 builds though, and offline requirements. Offline requirements are not a problem; on RHEL 8 you just have to install with pip in order to build docs offline. But yes, RHEL 9 is still using platform Python and therefore 3.4.3 remains the limit even after we stop supporting bullseye. Paolo
On Wed, Jul 3, 2024 at 8:12 AM Paolo Bonzini <pbonzini@redhat.com> wrote: > On Wed, Jul 3, 2024 at 2:06 PM John Snow <jsnow@redhat.com> wrote: > > On Wed, Jul 3, 2024, 4:00 AM Paolo Bonzini <pbonzini@redhat.com> wrote: > >> On 7/2/24 21:59, John Snow wrote: > >> > With RHEL 8 support retired (It's been two years today since RHEL 9 > >> > came out), our very oldest build platform version of Sphinx is now > >> > 3.4.3; and keeping backwards compatibility for versions as old as v1.6 > >> > when using domain extensions is a lot of work we don't need to do. > >> > >> Technically that's unrelated: thanks to your venv work, :) builds on > >> RHEL 8 / CentOS Stream 8 do not pick the platform Sphinx, because it > >> runs under Python 3.6. Therefore the version included in RHEL 8 does > >> not matter for picking the minimum supported Sphinx version. > > > > I think I can't mandate 4.x because of RHEL 9 builds though, and offline > requirements. > > Offline requirements are not a problem; on RHEL 8 you just have to > install with pip in order to build docs offline. But yes, RHEL 9 is > still using platform Python and therefore 3.4.3 remains the limit even > after we stop supporting bullseye. > To be clear I mean offline, isolated RPM builds under RHEL9 where I don't think we can utilize PyPI at all; and vendoring Sphinx is I think not a practical option due to the number of dependencies and non-pure Python deps. It's not a problem for developer workflow, just downstream packaging. Luckily OpenSUSE offers newer Sphinx, but RHEL doesn't yet. Maybe that can be rectified eventually - possibly after 3.8 is EOL and there is increased demand for newer Python packages to be made available in RHEL... but not yet, today. > > Paolo > > Thanks for the ack O:-)
On Wed, Jul 3, 2024 at 5:25 PM John Snow <jsnow@redhat.com> wrote: > To be clear I mean offline, isolated RPM builds under RHEL9 where I don't think we can utilize PyPI at all; and vendoring Sphinx is I think not a practical option due to the number of dependencies and non-pure Python deps. > > It's not a problem for developer workflow, just downstream packaging. Agreed, switching to PyPI packages is not something that should be done lightly---only after the platform Python is EOL, and only if there are benefits for QEMU to require 3.9 (like there were for 3.7). In that case, downstream could still package QEMU but they'd have to build python39-sphinx or something like that. Paolo > Luckily OpenSUSE offers newer Sphinx, but RHEL doesn't yet. Maybe that can be rectified eventually - possibly after 3.8 is EOL and there is increased demand for newer Python packages to be made available in RHEL... but not yet, today. > >> >> >> Paolo >> > > Thanks for the ack O:-)
diff --git a/docs/conf.py b/docs/conf.py index aae0304ac6e..876f6768815 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -53,10 +53,9 @@ # If your documentation needs a minimal Sphinx version, state it here. # -# Sphinx 1.5 and earlier can't build our docs because they are too -# picky about the syntax of the argument to the option:: directive -# (see Sphinx bugs #646, #3366). -needs_sphinx = '1.6' +# 3.4.3 is the oldest version of Sphinx that ships on a platform we +# pledge build support for. +needs_sphinx = '3.4.3' # 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/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index f270b494f01..9a0cfcbce75 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -31,6 +31,7 @@ from docutils.statemachine import ViewList from docutils.parsers.rst import directives, Directive from sphinx.errors import ExtensionError +from sphinx.util.docutils import switch_source_input from sphinx.util.nodes import nested_parse_with_titles import sphinx from qapi.gen import QAPISchemaVisitor @@ -38,15 +39,6 @@ from qapi.schema import QAPISchema -# Sphinx up to 1.6 uses AutodocReporter; 1.7 and later -# use switch_source_input. Check borrowed from kerneldoc.py. -Use_SSI = sphinx.__version__[:3] >= '1.7' -if Use_SSI: - from sphinx.util.docutils import switch_source_input -else: - from sphinx.ext.autodoc import AutodocReporter - - __version__ = '1.0' @@ -517,23 +509,8 @@ def do_parse(self, rstlist, node): subheadings (titles) without confusing the rendering of anything else. """ - # This is from kerneldoc.py -- it works around an API change in - # Sphinx between 1.6 and 1.7. Unlike kerneldoc.py, we use - # sphinx.util.nodes.nested_parse_with_titles() rather than the - # plain self.state.nested_parse(), and so we can drop the saving - # of title_styles and section_level that kerneldoc.py does, - # because nested_parse_with_titles() does that for us. - if Use_SSI: - with switch_source_input(self.state, rstlist): - nested_parse_with_titles(self.state, rstlist, node) - else: - save = self.state.memo.reporter - self.state.memo.reporter = AutodocReporter( - rstlist, self.state.memo.reporter) - try: - nested_parse_with_titles(self.state, rstlist, node) - finally: - self.state.memo.reporter = save + with switch_source_input(self.state, rstlist): + nested_parse_with_titles(self.state, rstlist, node) def setup(app): diff --git a/pythondeps.toml b/pythondeps.toml index 9c16602d303..bc656376caa 100644 --- a/pythondeps.toml +++ b/pythondeps.toml @@ -23,7 +23,7 @@ meson = { accepted = ">=0.63.0", installed = "1.2.3", canary = "meson" } [docs] # Please keep the installed versions in sync with docs/requirements.txt -sphinx = { accepted = ">=1.6", installed = "5.3.0", canary = "sphinx-build" } +sphinx = { accepted = ">=3.4.3", installed = "5.3.0", canary = "sphinx-build" } sphinx_rtd_theme = { accepted = ">=0.5", installed = "1.1.1" } [avocado]
With RHEL 8 support retired (It's been two years today since RHEL 9 came out), our very oldest build platform version of Sphinx is now 3.4.3; and keeping backwards compatibility for versions as old as v1.6 when using domain extensions is a lot of work we don't need to do. This patch is motivated by my work creating a new QAPI domain, which unlike the dbus documentation, cannot be allowed to regress by creating a "dummy" doc. Easier is to improve our minimum version as far as we can push it forwards, reducing my burden in creating cross-compatibility hacks and patches. A sampling of sphinx versions from various distributions, courtesy https://repology.org/project/python:sphinx/versions Alpine 3.16: v4.3.0 (QEMU support ended 2024-05-23) Alpine 3.17: v5.3.0 Alpine 3.18: v6.1.3 Alpine 3.19: v6.2.1 Ubuntu 20.04 LTS: EOL Ubuntu 22.04 LTS: v4.3.2 Ubuntu 22.10: EOL Ubuntu 23.04: EOL Ubuntu 23.10: v5.3.0 Ubuntu 24.04 LTS: v7.2.6 Debian 11: v3.4.3 (QEMU support ends 2024-07-xx) Debian 12: v5.3.0 Fedora 38: EOL Fedora 39: v6.2.1 Fedora 40: v7.2.6 CentOS Stream 8: v1.7.6 (QEMU support ended 2024-05-17) CentOS Stream 9: v3.4.3 OpenSUSE Leap 15.4: EOL OpenSUSE Leap 15.5: 2.3.1, 4.2.0 and 7.2.6 Signed-off-by: John Snow <jsnow@redhat.com> --- docs/conf.py | 7 +++---- docs/sphinx/qapidoc.py | 29 +++-------------------------- pythondeps.toml | 2 +- 3 files changed, 7 insertions(+), 31 deletions(-)