Merge branch 'main' into version-bumps

.github/workflows/ci.yml

@@ -113,7 +113,7 @@ jobs:
 
     - name: Store Coverage Data
       if: always() && contains('success,failure', steps.test.outcome)
-      uses: actions/[email protected].4
+      uses: actions/[email protected].5
       with:
         name: coverage-data-${{ matrix.platform }}-${{ matrix.python-version }}
         path: ".coverage.*"
@@ -168,7 +168,7 @@ jobs:
 
     - name: Upload Project Coverage HTML Report
       if: always() && steps.project-coverage.outcome == 'failure'
-      uses: actions/[email protected].4
+      uses: actions/[email protected].5
       with:
         name: html-coverage-report-project
         path: htmlcov

.readthedocs.yaml

@@ -7,7 +7,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:
     post_checkout:
       # RTD defaults to a depth of 50 but Briefcase versioning may require

changes/1936.misc.rst

@@ -0,0 +1 @@
+Updated actions/upload-artifact from 4.3.4 to 4.3.5.

changes/1938.misc.rst

@@ -0,0 +1 @@
+Updated coverage[toml] from 7.6.0 to 7.6.1.

changes/1939.misc.rst

@@ -0,0 +1 @@
+A missing quote in the example for the documentation of the New Command's ``-Q`` option was added.

changes/1940.misc.rst

@@ -0,0 +1 @@
+The environment for RTD builds was pinned, and protection for Sphinx updates was added.

changes/1942.doc.rst

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

docs/how-to/contribute-docs.rst

@@ -19,8 +19,11 @@ 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.
 

docs/reference/commands/new.rst

@@ -40,7 +40,7 @@ branch of the template.
 
 Override the answer to a new project prompt with the provided value.
 
-For instance, if ``-Q "license=MIT license`` is specified, then the question to
+For instance, if ``-Q "license=MIT license"`` is specified, then the question to
 choose a license will not be presented to the user and the MIT license will be
 automatically used for the project. When used in conjunction with ``--no-input``,
 the provided value overrides the default answer.

pyproject.toml

@@ -95,14 +95,16 @@ dependencies = [
 # Extras used by developers *of* briefcase are pinned to specific versions to
 # ensure environment consistency.
 dev = [
-    "coverage[toml] == 7.6.0",
+    "coverage[toml] == 7.6.1",
     "coverage-conditional-plugin == 0.9.0",
     "pre-commit == 3.8.0",
     "pytest == 8.3.2",
     "pytest-xdist == 3.6.1",
     "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",

tox.ini

@@ -99,6 +99,10 @@ build_dir = {[docs]docs_dir}{/}_build
 sphinx_args = --show-traceback --fail-on-warning --keep-going --jobs auto
 
 [testenv:docs{,-lint,-all,-live}]
+# 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
 extras = docs