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

[AlexWaygood]

https://github.com/python/cpython/commit/44b5c21f4124f9fa1312fada313c80c6abfa6d49
commit: 44b5c21f4124f9fa1312fada313c80c6abfa6d49
branch: main
author: Adam Turner <9087854+AA-Turner at users.noreply.github.com>
committer: AlexWaygood <Alex.Waygood at Gmail.com>
date: 2023-04-27T19:27:38+01:00
summary:

GH-103903: Test the minimum Sphinx version in CI (#103904)

files:
A Doc/requirements-oldest-sphinx.txt
M .github/workflows/doc.yml
M Doc/Makefile
M Doc/library/sqlite3.rst

diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
index 28300d891ed2..3f7550cc7294 100644
--- a/.github/workflows/doc.yml
+++ b/.github/workflows/doc.yml
@@ -79,6 +79,26 @@ jobs:
         # Build docs with the '-n' (nit-picky) option, convert warnings to errors (-W)
         make -C Doc/ PYTHON=../python SPHINXOPTS="-q -n -W --keep-going" html 2>&1
 
+  # 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 at v3
+    - name: 'Set up Python'
+      uses: actions/setup-python at 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 ebe7f3698000..c11ea6ce03e8 100644
--- 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 d47bcbfef8c4..743915688dae 100644
--- a/Doc/library/sqlite3.rst
+++ b/Doc/library/sqlite3.rst
@@ -310,7 +310,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.
 
@@ -337,7 +337,7 @@ Module functions
        The default will change to ``False`` in a future Python release.
    :type autocommit: bool
 
-   :rtype: Connection
+   :rtype: ~sqlite3.Connection
 
    .. audit-event:: sqlite3.connect database sqlite3.connect
    .. audit-event:: sqlite3.connect/handle connection_handle sqlite3.connect
@@ -1129,7 +1129,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
index 000000000000..d0390a04ea6d
--- /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