[3.11] GH-103903: Test the minimum Sphinx version in CI (#103904) (#103948)

[3.11] GH-103903: Test the minimum Sphinx version in CI (GH-103904).

(cherry picked from commit 44b5c21f4124f9fa1312fada313c80c6abfa6d49)

diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
index 77319c9f911247c2a41212f54396978437bbded1..e32078c67fba6095ded84653ca42f1112d7da34c 100644 (file)
--- a/.github/workflows/doc.yml
+++ b/.github/workflows/doc.yml
@@ -59,6 +59,26 @@ jobs:
         name: doc-html
         path: Doc/build/html
 
+  # This build doesn't use problem matchers or check annotations
+  # It also does not run 'make check', as sphinx-lint is not installed into the
+  # environment.
+  build_doc_oldest_supported_sphinx:
+    name: 'Docs (Oldest Sphinx)'
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    steps:
+    - uses: actions/checkout@v3
+    - name: 'Set up Python'
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.11'  # known to work with Sphinx 3.2
+        cache: 'pip'
+        cache-dependency-path: 'Doc/requirements-oldest-sphinx.txt'
+    - name: 'Install build dependencies'
+      run: make -C Doc/ venv REQUIREMENTS="requirements-oldest-sphinx.txt"
+    - name: 'Build HTML documentation'
+      run: make -C Doc/ SPHINXOPTS="-q" SPHINXERRORHANDLING="-W --keep-going" html
+
   # Run "doctest" on HEAD as new syntax doesn't exist in the latest stable release
   doctest:
     name: 'Doctest'

diff --git a/Doc/Makefile b/Doc/Makefile
index 1814d4e86eb067a0b9d544e688bdf46417179cb8..918814140f45cbe8b410de21f0605ffb01e7de91 100644 (file)
--- a/Doc/Makefile
+++ b/Doc/Makefile
@@ -13,6 +13,7 @@ JOBS         = auto
 PAPER        =
 SOURCES      =
 DISTVERSION  = $(shell $(PYTHON) tools/extensions/patchlevel.py)
+REQUIREMENTS = requirements.txt
 SPHINXERRORHANDLING = -W
 
 # Internal variables.
@@ -154,8 +155,8 @@ venv:
                echo "To recreate it, remove it first with \`make clean-venv'."; \
        else \
                $(PYTHON) -m venv $(VENVDIR); \
-               $(VENVDIR)/bin/python3 -m pip install -U pip setuptools; \
-               $(VENVDIR)/bin/python3 -m pip install -r requirements.txt; \
+               $(VENVDIR)/bin/python3 -m pip install --upgrade pip; \
+               $(VENVDIR)/bin/python3 -m pip install -r $(REQUIREMENTS); \
                echo "The venv has been created in the $(VENVDIR) directory"; \
        fi
 

diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst
index a87e8429e6dfe30263d980f266ecae99c6264f85..165bac4c0f707bc913657ada944e0ec4178e7f67 100644 (file)
--- a/Doc/library/sqlite3.rst
+++ b/Doc/library/sqlite3.rst
@@ -307,7 +307,7 @@ Module functions
        to avoid data corruption.
        See :attr:`threadsafety` for more information.
 
-   :param Connection factory:
+   :param ~sqlite3.Connection factory:
        A custom subclass of :class:`Connection` to create the connection with,
        if not the default :class:`Connection` class.
 
@@ -325,7 +325,7 @@ Module functions
        The query string allows passing parameters to SQLite,
        enabling various :ref:`sqlite3-uri-tricks`.
 
-   :rtype: Connection
+   :rtype: ~sqlite3.Connection
 
    .. audit-event:: sqlite3.connect database sqlite3.connect
    .. audit-event:: sqlite3.connect/handle connection_handle sqlite3.connect
@@ -1035,7 +1035,7 @@ Connection objects
       Works even if the database is being accessed by other clients
       or concurrently by the same connection.
 
-      :param Connection target:
+      :param ~sqlite3.Connection target:
           The database connection to save the backup to.
 
       :param int pages:

diff --git a/Doc/requirements-oldest-sphinx.txt b/Doc/requirements-oldest-sphinx.txt
new file mode 100644 (file)
index 0000000..d0390a0
--- /dev/null
+++ b/Doc/requirements-oldest-sphinx.txt
@@ -0,0 +1,38 @@
+# Requirements to build the Python documentation, for the oldest supported
+# Sphinx version.
+#
+# We pin Sphinx and all of its dependencies to ensure a consistent environment.
+
+blurb
+python-docs-theme>=2022.1
+
+# Generated from:
+#     pip install "Sphinx~=3.2.0" "docutils<0.17" "Jinja2<3" "MarkupSafe<2"
+#     pip freeze
+#
+# Sphinx 3.2 comes from ``needs_sphinx = '3.2'`` in ``Doc/conf.py``.
+# Docutils<0.17, Jinja2<3, and MarkupSafe<2 are additionally specified as
+# Sphinx 3.2 is incompatible with newer releases of these packages.
+
+Sphinx==3.2.1
+alabaster==0.7.13
+Babel==2.12.1
+certifi==2022.12.7
+charset-normalizer==3.1.0
+colorama==0.4.6
+docutils==0.16
+idna==3.4
+imagesize==1.4.1
+Jinja2==2.11.3
+MarkupSafe==1.1.1
+packaging==23.1
+Pygments==2.15.1
+requests==2.29.0
+snowballstemmer==2.2.0
+sphinxcontrib-applehelp==1.0.4
+sphinxcontrib-devhelp==1.0.2
+sphinxcontrib-htmlhelp==2.0.1
+sphinxcontrib-jsmath==1.0.1
+sphinxcontrib-qthelp==1.0.3
+sphinxcontrib-serializinghtml==1.1.5
+urllib3==1.26.15