Add explicit RTD version pin, and protect against Sphinx 8 deprecations

.readthedocs.yaml

@@ -7,9 +7,8 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    # On Python 3.12, pip fails with AttributeError: module 'pkgutil' has no attribute
-    # 'ImpImporter', probably because readthedocs provides an old version of pip.
-    python: "3.11"
+    # Docs are always built on Python 3.12. See also the tox config and contribution docs.
+    python: "3.12"
   jobs:
     post_checkout:
       # RTD defaults to a depth of 50 but Toga versioning may require

changes/2745.doc.rst

@@ -0,0 +1 @@
+Building Toga's documentation now requires the use of Python 3.12.

core/pyproject.toml

@@ -80,17 +80,15 @@ dev = [
     # typing-extensions needed for TypeAlias added in Py 3.10
     "typing-extensions == 4.9.0 ; python_version < '3.10'",
 ]
+# Docs are always built on a specific Python version; see RTD and tox config files,
+# and the docs contribution guide.
 docs = [
     "furo == 2024.7.18",
     "Pillow == 10.4.0",
     "pyenchant == 3.2.2",
-    # Sphinx 7.2 deprecated support for Python 3.8
-    "sphinx == 7.1.2 ; python_version < '3.9'",
-    "sphinx == 7.3.7 ; python_version >= '3.9'",
+    "sphinx == 7.3.7",
     "sphinx_tabs == 3.4.5",
-    # Sphinx 2024.2.4 deprecated support for Python 3.8
-    "sphinx-autobuild == 2021.3.14 ; python_version < '3.9'",
-    "sphinx-autobuild == 2024.4.16 ; python_version >= '3.9'",
+    "sphinx-autobuild == 2024.4.16",
     "sphinx-csv-filter == 0.4.1",
     "sphinx-copybutton == 0.5.2",
     "sphinx-toolbox == 3.7.0",

docs/how-to/contribute/docs.rst

@@ -14,8 +14,11 @@ documentation.
 Building Toga's documentation
 =============================
 
-To build Toga's documentation, start by :ref:`setting up a development
-environment <setup-dev-environment>`.
+.. Docs are always built on Python 3.12. See also the RTD and tox config.
+
+To build Toga's documentation, start by :ref:`setting up a development environment
+<setup-dev-environment>`.You **must** have a Python 3.12 interpreter installed and
+available on your path (i.e., ``python3.12`` must start a Python 3.12 interpreter).
 
 You'll also need to install the Enchant spell checking library.
 

tox.ini

@@ -82,16 +82,11 @@ commands =
 [docs]
 docs_dir = {tox_root}{/}docs
 build_dir = {[docs]docs_dir}{/}_build
-# replace when Sphinx>=7.3 and Python 3.8 is dropped:
-#  -T => --show-traceback
-#  -W => --fail-on-warning
-#  -b => --builder
-#  -v => --verbose
-#  -a => --write-all
-#  -E => --fresh-env
-sphinx_args = -T -W --keep-going --jobs auto
+sphinx_args = --show-traceback --fail-on-warning --keep-going --jobs auto
 
 [testenv:docs{,-lint,-all,-live,-live-src}]
+# Docs are always built on Python 3.12. See also the RTD config and contribution docs.
+base_python = py312
 skip_install = True
 # give sphinx-autobuild time to shutdown http server
 suicide_timeout = 1
@@ -104,9 +99,9 @@ passenv =
     #     export PYENCHANT_LIBRARY_PATH=/opt/homebrew/lib/libenchant-2.2.dylib
     PYENCHANT_LIBRARY_PATH
 commands =
-    !lint-!all-!live : python -m sphinx {[docs]sphinx_args} {posargs} -b html {[docs]docs_dir} {[docs]build_dir}{/}html
-    lint : python -m sphinx {[docs]sphinx_args} {posargs} -b spelling {[docs]docs_dir} {[docs]build_dir}{/}spell
-    lint : python -m sphinx {[docs]sphinx_args} {posargs} -b linkcheck {[docs]docs_dir} {[docs]build_dir}{/}links
-    all  : python -m sphinx {[docs]sphinx_args} {posargs} -v -a -E -b html {[docs]docs_dir} {[docs]build_dir}{/}html
-    live-!src : sphinx-autobuild {[docs]sphinx_args} {posargs} -b html {[docs]docs_dir} {[docs]build_dir}{/}live
-    live-src  : sphinx-autobuild {[docs]sphinx_args} {posargs} -a -E --watch {tox_root}{/}core{/}src{/}toga -b html {[docs]docs_dir} {[docs]build_dir}{/}live
+    !lint-!all-!live : python -m sphinx {[docs]sphinx_args} {posargs} --builder html {[docs]docs_dir} {[docs]build_dir}{/}html
+    lint : python -m sphinx {[docs]sphinx_args} {posargs} --builder spelling {[docs]docs_dir} {[docs]build_dir}{/}spell
+    lint : python -m sphinx {[docs]sphinx_args} {posargs} --builder linkcheck {[docs]docs_dir} {[docs]build_dir}{/}links
+    all  : python -m sphinx {[docs]sphinx_args} {posargs} --verbose --write-all --fresh-env --builder html {[docs]docs_dir} {[docs]build_dir}{/}html
+    live-!src : sphinx-autobuild {[docs]sphinx_args} {posargs} --builder html {[docs]docs_dir} {[docs]build_dir}{/}live
+    live-src  : sphinx-autobuild {[docs]sphinx_args} {posargs} --write-all --fresh-env --watch {tox_root}{/}core{/}src{/}toga --builder html {[docs]docs_dir} {[docs]build_dir}{/}live