Fix docs environment to Python 3.12.

.readthedocs.yaml

@@ -7,6 +7,7 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
+    # Docs are always built on Python 3.12. See also the tox config and contribution docs.
     python: "3.12"
   jobs:
     post_checkout:

changes/1942.doc.rst

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

docs/how-to/contribute-docs.rst

@@ -19,8 +19,11 @@ the other index files for clues.
 Build documentation locally
 ---------------------------
 
+.. Docs are always built on Python 3.12. See also the RTD and tox config.
+
 To build the documentation locally, :ref:`set up a development environment
-<setup-dev-environment>`.
+<setup-dev-environment>`. However, 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.
 

pyproject.toml

@@ -106,18 +106,14 @@ dev = [
     "setuptools_scm == 8.1.0",
     "tox == 4.16.0",
 ]
+# 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",
     "pyenchant == 3.2.2",
-    # Sphinx 7.2 deprecated support for Python 3.8
-    # Sphinx 8.0 deprecated support for Python 3.9
-    "sphinx == 7.1.2 ; python_version < '3.9'",
-    "sphinx == 7.4.7 ; python_version == '3.9'",
-    "sphinx == 7.4.7 ; python_version >= '3.10'",
+    "sphinx == 7.4.7",
     "sphinx_tabs == 3.4.5",
-    # sphinx-autobuild 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-copybutton == 0.5.2",
     "sphinxcontrib-spelling == 8.0.0",
 ]

tox.ini

@@ -98,16 +98,13 @@ 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}]
+# Docs are always built on Python 3.12. See also the RTD config and contribution docs.
+base_python = py312
+# give sphinx-autobuild time to shutdown http server
+suicide_timeout = 1
 package = wheel
 wheel_build_env = .pkg
 extras = docs
@@ -117,8 +114,8 @@ 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 : sphinx-autobuild {[docs]sphinx_args} {posargs} -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 : sphinx-autobuild {[docs]sphinx_args} {posargs} --builder html {[docs]docs_dir} {[docs]build_dir}{/}live