From 27eefbff3040988df3a26c6cf48d71f6c4e398f4 Mon Sep 17 00:00:00 2001 From: Russell Keith-Magee Date: Tue, 6 Aug 2024 08:27:31 +0800 Subject: [PATCH 1/5] Add explicit RTD version pin, and protect against Sphinx 8 deprecations --- .readthedocs.yaml | 4 +--- core/pyproject.toml | 6 ++++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 9bc3d0f0e1..b4f1b7b149 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -7,9 +7,7 @@ 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" + python: "3.12" jobs: post_checkout: # RTD defaults to a depth of 50 but Toga versioning may require diff --git a/core/pyproject.toml b/core/pyproject.toml index 061be611d4..5d6c40f450 100644 --- a/core/pyproject.toml +++ b/core/pyproject.toml @@ -85,10 +85,12 @@ docs = [ "Pillow == 10.4.0", "pyenchant == 3.2.2", # Sphinx 7.2 deprecated support for Python 3.8 + # Sphinx 8.0 deprecated support for Python 3.8 "sphinx == 7.1.2 ; python_version < '3.9'", - "sphinx == 7.3.7 ; python_version >= '3.9'", + "sphinx == 7.4.7 ; python_version == '3.9'", + "sphinx == 7.4.7 ; python_version >= '3.10'", "sphinx_tabs == 3.4.5", - # Sphinx 2024.2.4 deprecated support for Python 3.8 + # 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-csv-filter == 0.4.1", From ad21326b261414b4e0525abcca0e81a9778132ab Mon Sep 17 00:00:00 2001 From: Russell Keith-Magee Date: Tue, 6 Aug 2024 08:30:59 +0800 Subject: [PATCH 2/5] Add changenote. --- changes/2745.misc.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 changes/2745.misc.rst diff --git a/changes/2745.misc.rst b/changes/2745.misc.rst new file mode 100644 index 0000000000..054f72bfed --- /dev/null +++ b/changes/2745.misc.rst @@ -0,0 +1 @@ +The environment for RTD builds was pinned, and protection for Sphinx updates was added. From 80de5a7d8684ad4322b9fad6f4cf677592a197f3 Mon Sep 17 00:00:00 2001 From: Russell Keith-Magee Date: Tue, 6 Aug 2024 08:41:36 +0800 Subject: [PATCH 3/5] Revert the Sphinx version bump because of incompatibility with sphinx-csv-filter. --- core/pyproject.toml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/core/pyproject.toml b/core/pyproject.toml index 5d6c40f450..6d55c35d5a 100644 --- a/core/pyproject.toml +++ b/core/pyproject.toml @@ -87,8 +87,8 @@ docs = [ # Sphinx 7.2 deprecated support for Python 3.8 # Sphinx 8.0 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 ; python_version >= '3.10'", + "sphinx == 7.3.7 ; python_version == '3.9'", + "sphinx == 7.3.7 ; python_version >= '3.10'", "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'", From 58890a5091971dd3a7e7a6bcfbab223a9687aea3 Mon Sep 17 00:00:00 2001 From: Russell Keith-Magee Date: Wed, 7 Aug 2024 09:17:11 +0800 Subject: [PATCH 4/5] Fix docs environment to Python 3.12. --- changes/2745.doc.rst | 1 + changes/2745.misc.rst | 1 - core/pyproject.toml | 12 ++++-------- docs/how-to/contribute/docs.rst | 5 +++-- tox.ini | 22 ++++++++-------------- 5 files changed, 16 insertions(+), 25 deletions(-) create mode 100644 changes/2745.doc.rst delete mode 100644 changes/2745.misc.rst 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/changes/2745.misc.rst b/changes/2745.misc.rst deleted file mode 100644 index 054f72bfed..0000000000 --- a/changes/2745.misc.rst +++ /dev/null @@ -1 +0,0 @@ -The environment for RTD builds was pinned, and protection for Sphinx updates was added. diff --git a/core/pyproject.toml b/core/pyproject.toml index 6d55c35d5a..aad18fae8d 100644 --- a/core/pyproject.toml +++ b/core/pyproject.toml @@ -80,19 +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 Py3.12; 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 8.0 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 ; python_version >= '3.10'", + "sphinx == 7.3.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-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..4e166484a4 100644 --- a/docs/how-to/contribute/docs.rst +++ b/docs/how-to/contribute/docs.rst @@ -14,8 +14,9 @@ documentation. Building Toga's documentation ============================= -To build Toga's documentation, start by :ref:`setting up a development -environment `. +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..adf897e377 100644 --- a/tox.ini +++ b/tox.ini @@ -82,16 +82,10 @@ 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}] +base_python = py312 skip_install = True # give sphinx-autobuild time to shutdown http server suicide_timeout = 1 @@ -104,9 +98,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 From 0c3a4383adcb44ce8ea282887c76cd2ae10b8b3a Mon Sep 17 00:00:00 2001 From: Russell Keith-Magee Date: Thu, 8 Aug 2024 07:18:34 +0800 Subject: [PATCH 5/5] Add comment breadcrumbs to ensure configs stay in sync. --- .readthedocs.yaml | 1 + core/pyproject.toml | 2 +- docs/how-to/contribute/docs.rst | 2 ++ tox.ini | 1 + 4 files changed, 5 insertions(+), 1 deletion(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index b4f1b7b149..4be7c3148e 100644 --- a/.readthedocs.yaml +++ b/.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: diff --git a/core/pyproject.toml b/core/pyproject.toml index aad18fae8d..8f359995e7 100644 --- a/core/pyproject.toml +++ b/core/pyproject.toml @@ -80,7 +80,7 @@ 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 Py3.12; see RTD and tox config files, +# 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", diff --git a/docs/how-to/contribute/docs.rst b/docs/how-to/contribute/docs.rst index 4e166484a4..5fa44ff1f2 100644 --- a/docs/how-to/contribute/docs.rst +++ b/docs/how-to/contribute/docs.rst @@ -14,6 +14,8 @@ documentation. Building Toga's documentation ============================= +.. 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). diff --git a/tox.ini b/tox.ini index adf897e377..39b5894468 100644 --- a/tox.ini +++ b/tox.ini @@ -85,6 +85,7 @@ build_dir = {[docs]docs_dir}{/}_build 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