diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 9bc3d0f0e1..4be7c3148e 100644 --- a/.readthedocs.yaml +++ b/.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 diff --git a/changes/2745.doc.rst b/changes/2745.doc.rst new file mode 100644 index 0000000000..c4762e91ca --- /dev/null +++ b/changes/2745.doc.rst @@ -0,0 +1 @@ +Building Toga's documentation now requires the use of Python 3.12. diff --git a/core/pyproject.toml b/core/pyproject.toml index 061be611d4..8f359995e7 100644 --- a/core/pyproject.toml +++ b/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", diff --git a/docs/how-to/contribute/docs.rst b/docs/how-to/contribute/docs.rst index f1d63fb02e..5fa44ff1f2 100644 --- a/docs/how-to/contribute/docs.rst +++ b/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 `. +.. 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 +`.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. diff --git a/tox.ini b/tox.ini index 00152d87f8..39b5894468 100644 --- a/tox.ini +++ b/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