Merge pull request #496 from beeware/rtd-py-version

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

Author: mhsmith

.readthedocs.yml

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

changes/496.doc.rst

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

docs/how-to/contribute-docs.rst

@@ -19,8 +19,12 @@ study 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.
 Enchant can be installed using `Homebrew <https://brew.sh>`__:

pyproject.toml

@@ -55,16 +55,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 == 7.1.2 ; python_version < '3.9'",
-    "sphinx == 7.4.7 ; python_version >= '3.9'",
+    "sphinx == 7.4.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-copybutton == 0.5.2",
     "sphinxcontrib-spelling == 8.0.0",
 ]

tox.ini

@@ -42,29 +42,25 @@ 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
+# give sphinx-autobuild time to shutdown http server
+suicide_timeout = 1
 package = wheel
 wheel_build_env = .pkg
-change_dir = docs
 extras = docs
 passenv =
     # On macOS M1, you need to manually set the location of the PyEnchant
     # library:
     #     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}{/}src{/}rubicon{/}objc -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}{/}src{/}rubicon{/}objc --builder html {[docs]docs_dir} {[docs]build_dir}{/}live