diff --git a/.readthedocs.yml b/.readthedocs.yml index c29b5267..61478e90 100644 --- a/.readthedocs.yml +++ b/.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 diff --git a/changes/496.doc.rst b/changes/496.doc.rst new file mode 100644 index 00000000..890ca1e3 --- /dev/null +++ b/changes/496.doc.rst @@ -0,0 +1 @@ +Building Rubicon ObjC's documentation now requires the use of Python 3.12. diff --git a/docs/how-to/contribute-docs.rst b/docs/how-to/contribute-docs.rst index e2150196..b59417a0 100644 --- a/docs/how-to/contribute-docs.rst +++ b/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 -`. +`. 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 `__: diff --git a/pyproject.toml b/pyproject.toml index 51f85426..06c0d2a6 100644 --- a/pyproject.toml +++ b/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", ] diff --git a/tox.ini b/tox.ini index c9f60d91..1a4d437e 100644 --- a/tox.ini +++ b/tox.ini @@ -42,19 +42,15 @@ 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 @@ -62,9 +58,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}{/}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