Merge branch 'main' into trallard/patch-JS-bundle

.github/workflows/CI.yml

@@ -33,14 +33,7 @@ jobs:
       matrix:
         # macos-14==latest
         # ubuntu-20.04==latest
-        os:
-          [
-            "ubuntu-latest",
-            "ubuntu-24.04",
-            "macos-14",
-            "macos-13",
-            "windows-latest",
-          ]
+        os: ["ubuntu-latest", "ubuntu-24.04", "macos-14", "windows-latest"]
         python-version: ["3.9", "3.10", "3.11", "3.12"]
         sphinx-version: [""]
         include:
@@ -74,15 +67,15 @@ jobs:
       - name: "Run tests ✅"
         shell: bash
         run: |
-          # this will compile the assets then run the tests
+          # this will compile the assets and translations then run the tests
           # check if there is a specific Sphinx version to test with
-          # example substitution: tox run -e compile,py39-sphinx61-tests
+          # example substitution: tox run -e compile-assets,i18n-compile,py39-sphinx61-tests
           if [ -n "${{matrix.sphinx-version}}" ]; then
-            python -Im tox run -e compile,py$(echo ${{ matrix.python-version }} | tr -d .)-sphinx$(echo ${{ matrix.sphinx-version }} | tr -d .)-tests
+            python -Im tox run -e compile-assets,i18n-compile,py$(echo ${{ matrix.python-version }} | tr -d .)-sphinx$(echo ${{ matrix.sphinx-version }} | tr -d .)-tests
           # if not we use the default version
-          # example substitution: tox run -e compile,py39-tests
+          # example substitution: tox run -e compile-assets,i18n-compile,py39-tests
           else
-            python -Im tox run -e compile,py$(echo ${{ matrix.python-version }} | tr -d .)-tests
+            python -Im tox run -e compile,i18n-compile,py$(echo ${{ matrix.python-version }} | tr -d .)-tests
           fi
       - name: "Upload coverage data to GH artifacts 📤"
         if: matrix.python-version == '3.12' && matrix.os == 'ubuntu-latest' && matrix.sphinx-version == 'dev'
@@ -108,7 +101,7 @@ jobs:
           graphviz: true
       - name: "Run accessibility tests with playwright 🎭"
         # build PST, build docs, then run a11y-tests
-        run: python -Im tox run -e py312-docs,a11y-tests
+        run: python -Im tox run -m a11y
 
   # Build our docs (PST) on major OSes and check for warnings
   build-site:

.github/workflows/prerelease.yml

@@ -37,7 +37,7 @@ jobs:
       - name: "Run tests ✅ (no coverage)"
         run: |
           # this will compile the assets then run the tests
-          python -Im tox run -e compile,py$(echo ${{ matrix.python-version }} | tr -d .)-tests-no-cov
+          python -Im tox run -e compile-assets,i18n-compile,py$(echo ${{ matrix.python-version }} | tr -d .)-tests-no-cov
           echo "PYTEST_ERRORS=$?" >> $GITHUB_ENV
 
       # If either the docs build or the tests resulted in an error, create an issue to note it

.github/workflows/publish.yml

@@ -39,10 +39,6 @@ jobs:
           python-version: "3.9"
           pandoc: "False"
 
-      - name: "Install gettext for translations 🌐"
-        run: |
-          sudo apt-get install gettext
-
       - name: "Build and inspect package 📦"
         uses: hynek/build-and-inspect-python-package@v2
         id: baipp

docs/community/setup.md

@@ -7,9 +7,8 @@ If you are comfortable with and prefer a more manual setup refer to the [](topic
 
 ## Testing pre-release and nightly
 
-You can test the alpha, beta
-and release candidates of pydata sphinx theme on your your projects. To do so
-simply install with pip using the `--pre` flag:
+You can test the alpha, beta and release candidates of the PyData Sphinx theme on your projects.
+To do so install with pip using the `--pre` flag:
 
 ```console
 $ pip install --pre pydata-sphinx-theme
@@ -20,9 +19,9 @@ If an `alpha`, `beta` or `rc` is available, pip will install it.
 You can use the `--pre` flag in your project's continuous integration test suite
 to catch regressions or bugs before their release.
 
-If you are even more adventurous pydata-sphinx-theme has nightly builds, you can try following the
+If you are even more adventurous `pydata-sphinx-theme` has nightly builds, you can try following the
 instructions provided [on the scientific-python/upload-nightly-action
-Readme](https://github.com/scientific-python/upload-nightly-action?tab=readme-ov-file#using-nightly-builds-in-ci)
+README](https://github.com/scientific-python/upload-nightly-action?tab=readme-ov-file#using-nightly-builds-in-ci)
 on installing nightly wheels.
 
 Installing nightly wheels in your project's CI jobs is a great way to help theme developers catch bugs ahead of
@@ -145,6 +144,14 @@ $ python -m http.server -d docs/_build/html/
 
 This will print a local URL that you can open in a browser to explore the HTML files.
 
+You can also serve the documentation with live-reload using the following command:
+
+```console
+$ tox run -e docs-live
+```
+
+This command will build the documentation and watch for any changes to the `doc` folder and rebuild the documentation automatically.
+
 ### Change content and re-build
 
 Now that you've built the documentation, edit one of the source files to see how the documentation updates with new builds.
@@ -162,7 +169,7 @@ These are then built and bundled with the theme (e.g., `scss` is turned into `cs
 To compile the CSS/JS assets with `tox`, run the following command:
 
 ```console
-$ tox run -e compile
+$ tox run -e compile-assets
 ```
 
 This will compile all assets and place them in the appropriate folder to be used with documentation builds.
@@ -174,12 +181,14 @@ The `sphinx-theme-builder` will bundle these assets automatically when we make a
 
 ## Run a development server
 
-You can combine the above two actions (build the docs and compile JS/CSS assets) and run a development server so that changes to `src/` are automatically bundled with the package, and the documentation is immediately reloaded in a live preview window.
+You can combine the above two actions (build the docs and compile JS/CSS assets) and run a development server so that
+changes to `src/` are automatically bundled with the package, and the documentation is immediately reloaded in a live preview window.
 
 To run the development server with `tox`, run the following command:
 
 ```console
-$ tox run -e docs-live
+# note the -m flag vs. other commands in this guide
+$ tox run -m docs-live-server
 ```
 
 When working on the theme, making changes to any of these directories: