Skip to content

Fix docs environment to Python 3.12. #1942

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mhsmith merged 5 commits into from
Aug 7, 2024
Merged

Fix docs environment to Python 3.12. #1942

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
c7f500e
Fix docs environment to Python 3.12.
freakboy3742 Aug 7, 2024
73b4c21
Add changenote.
freakboy3742 Aug 7, 2024
0732443
Use consistent syntax for base environments.
freakboy3742 Aug 7, 2024
f5765ce
Add timeout for live docs.
freakboy3742 Aug 7, 2024
a0a2baa
Add comment breadcrumbs to ensure configs stay in sync.
freakboy3742 Aug 7, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changes/1942.doc.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Building Briefcase's documentation now requires the use of Python 3.12.
3 changes: 2 additions & 1 deletion docs/how-to/contribute-docs.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,8 @@ Build documentation locally
---------------------------

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.

Expand Down
12 changes: 4 additions & 8 deletions pyproject.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,18 +106,14 @@ dev = [
"setuptools_scm == 8.1.0",
"tox == 4.16.0",
]
# Docs are always built on Py3.12; 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",
]
Expand Down
20 changes: 7 additions & 13 deletions tox.ini
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,16 +98,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}]
basepython = python3.12
Copy link
Copy Markdown
Member

@rmartin16 rmartin16 Aug 7, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For consistency :) or perhaps the coverage section could be updated to match this

Suggested change
basepython = python3.12
base_python = py312

Copy link
Copy Markdown
Member Author

@freakboy3742 freakboy3742 Aug 7, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

WHY ARE THERE TWO VALID SYNTAXES FOR THIS!!>!!KJHKJH!OI&!^&!

package = wheel
wheel_build_env = .pkg
extras = docs
Expand All @@ -117,8 +111,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