Skip to content

Commit

Permalink
Merge branch 'main' into trallard/patch-JS-bundle
Browse files Browse the repository at this point in the history
  • Loading branch information
trallard authored Sep 18, 2024
2 parents 68b2649 + 8b36690 commit c3f822b
Show file tree
Hide file tree
Showing 25 changed files with 689 additions and 647 deletions.
21 changes: 7 additions & 14 deletions .github/workflows/CI.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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'
Expand All @@ -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:
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/prerelease.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 0 additions & 4 deletions .github/workflows/publish.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
25 changes: 17 additions & 8 deletions docs/community/setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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.
Expand All @@ -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.
Expand All @@ -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:
Expand Down
Loading

0 comments on commit c3f822b

Please sign in to comment.