-
Notifications
You must be signed in to change notification settings - Fork 336
/
Copy pathtox.ini
198 lines (187 loc) · 8.59 KB
/
tox.ini
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
[tox]
min_version = 4
# list of environments to run by default with tox run
# using Python 3.12 as the default, this needs to be kept in line with
# .github/actions/set-dev-env/action.yml (default Python version)
env_list =
lint,
compile-assets,
i18n-compile,
py312-docs,
py312-tests,
a11y-tests
# convenience label for running tests with a given Python version, aimed at
# helping contributors run common tasks without needing to call all the steps
# For example to run the tests: tox run -m tests
labels =
tests = compile-assets, i18n-compile, py312-tests
a11y = compile-assets, i18n-compile, py312-docs, a11y-tests
i18n = i18n-extract, i18n-compile
live-server = compile-assets, i18n-compile, docs-live
# general tox env configuration
# these can be run with any py3{9,12} version, for example:
# tox run -e py39-lint
[testenv]
deps =
lint: pre-commit
compile-assets: sphinx-theme-builder[cli]
profile-docs: py-spy
extras =
{docs-no-checks, docs-linkcheck, profile-docs}: doc
skip_install =
lint: true # do not need to install to lint
profile-docs: true # avoids issues with py-spy and setting the git repo
compile-assets: false
package = editable
commands =
lint: pre-commit run -a
compile-assets: stb compile # bundle JavaScript and Sass
# can substitute the target directory with any other directory by calling:
# tox run -e docs-no-checks -- path/to/other/directory
docs-no-checks: sphinx-build {posargs:audit}/site {posargs:audit}/_build
# example tox run -e py39-profile-docs -- -o profile.svg -n 100
profile-docs: python ./tools/profile.py {posargs}
# tests can be ran with or without coverage (see examples below),
# it is recommended to run compile-assets before running tests
# i18n-compile MUST be run before running tests
# (see examples below),
# tox run -e compile-assets,i18n-compile,py39-tests
# if you want to skip the assets and translations compilation step you can run
# the tests without `compile-assets,i18n-compile`, for example:
# tox run -e py39-tests
# run tests with a specific Sphinx version
# tox run -e compile-assets,i18n-compile,py39-sphinx61-tests
# run tests without coverage
# tox run -e compile-assets,i18n-compile,py39-tests-no-cov
[testenv:py3{9,10,11,12}{,-sphinx61,-sphinxdev,}-tests{,-no-cov}]
description = "Run tests Python and Sphinx versions. If a Sphinx version is specified, it will use that version vs the default in pyproject.toml"
# need to ensure the package is installed in editable mode
package = editable
extras =
test # install dependencies, includes pytest-playwright - defined in pyproject.toml
pass_env = GITHUB_ACTIONS # so we can check if this is run on GitHub Actions
deps =
coverage[toml]
py39-sphinx61-tests: sphinx~=6.1.0
py312-sphinxdev: sphinx[test] @ git+https://github.com/sphinx-doc/sphinx.git@master
depends =
compile-assets,
i18n-compile
allowlist_externals=
playwright
bash
commands =
bash -c 'if [[ "{env:GITHUB_ACTIONS:}" == "true" ]]; then playwright install --with-deps; else playwright install; fi'
py3{9,10,11,12}{,-sphinx61,-sphinxdev,}-tests: coverage run -m pytest -m "not a11y" {posargs}
py3{9,10,11,12}{,-sphinx61,-sphinxdev,}-tests-no-cov: pytest -m "not a11y" {posargs}
# run accessibility tests with Playwright and axe-core
# compiling the assets is needed before running the tests
# tox run -e compile,py312-docs,a11y-tests
# by default we will retain playwright traces on failure and run the tests on chromium
# to run the tests on firefox you can call:
# tox run -e compile,py312-docs,a11y-tests-firefox
[testenv:a11y-tests{-chromium,-firefox}]
description = "run accessibility tests with Playwright and axe-core"
base_python = py312 # keep in sync with tests.yml
pass_env = GITHUB_ACTIONS # so we can check if this is run on GitHub Actions
extras =
test # install dependencies, includes pytest-playwright - defined in pyproject.toml
depends =
compile-assets,
i18n-compile
py312-docs
allowlist_externals=
playwright
bash
commands =
bash -c 'if [[ "{env:GITHUB_ACTIONS:}" == "true" ]]; then playwright install --with-deps; else playwright install; fi'
a11y-tests{,-chromium}: pytest -m "a11y" --browser=chromium {posargs:--tracing=retain-on-failure}
a11y-tests-firefox: pytest -m "a11y" --browser=firefox {posargs:--tracing=retain-on-failure}
# build PST documentation with the default or a specific Sphinx version
# since we are building the documentation we install the packaged dev version of PST
# tox run -e py39-docs
# tox run -e py39-sphinx61-docs
[testenv:py3{9,12}{,-sphinx61}-docs]
description = build the documentation and place in docs/_build/html
# suppress Py3.11's new "can't debug frozen modules" warning
set_env = PYDEVD_DISABLE_FILE_VALIDATION=1
# keep this in sync across all docs environments
extras = {[testenv:docs-no-checks]extras}
deps =
py39-sphinx61-docs: sphinx~=6.1.0
commands =
sphinx-build -b html docs/ docs/_build/html -nTv -w warnings.txt
python tests/utils/check_warnings.py
# recommended for local development, this command will build the PST documentation
# with the default Sphinx version and the PST installed in editable mode
# tox run -e docs-dev
[testenv:docs-dev]
description = build the documentation and place in docs/_build/html (dev mode)
# suppress Py3.11's new "can't debug frozen modules" warning
set_env = PYDEVD_DISABLE_FILE_VALIDATION=1
# keep this in sync across all docs environments
extras = {[testenv:docs-no-checks]extras}
package = editable
commands =
sphinx-build -b html docs/ docs/_build/html -nTv -w warnings.txt {posargs}
python tests/utils/check_warnings.py
# build the docs with live-reload, if you are working on the docs only (no theme changes) the best option is to call
# tox run -e docs-live
# this will only watch the docs directory and rebuild the docs when changes are detected
# if you are working on the theme (HTML, jinja templates, JS, CSS) and the docs, you can call
# tox run -e docs-live-theme
[testenv:docs-live{,-theme}]
description = "Build and serve the documentation with live-reload"
extras =
dev
package = editable
deps =
sphinx-theme-builder[cli] @ git+https://github.com/pradyunsg/sphinx-theme-builder.git@main
# suppress Py3.11's new "can't debug frozen modules" warning
set_env = PYDEVD_DISABLE_FILE_VALIDATION=1
commands =
docs-live-theme: stb serve docs --open-browser --re-ignore=locale|api|_build|\.jupyterlite\.doit\.db
docs-live: sphinx-autobuild docs/ docs/_build/html --open-browser --re-ignore=locale|api|_build|\.jupyterlite\.doit\.db
# check external links in the documentation
# tox run -e docs-linkcheck
[testenv:docs-linkcheck]
description = "Check external links in the documentation"
extras = {[testenv:docs-no-checks]extras}
allowlist_externals = bash
basepython = py313
commands =
sphinx-build -b linkcheck docs/ docs/_build/linkcheck -w warnings.txt --keep-going -q
bash -c "echo 'Linkcheck complete; see docs/_build/linkcheck/output.txt for any errors'"
# extract translatable files into the POT file and update locale PO files
# tox run -e i18n-extract
# this will update all locales, to update a single locale you can
# pass the locale code, for example to update the Spanish locale only:
# tox run -e i18n-extract -- --locale=es
[testenv:i18n-extract]
description = "Extract translatable messages from the source code and update locale files"
extras = i18n
package = editable
allowlist_externals = bash
commands =
# explicitly pass this as a bash command to set PST_VERSION
bash -c "PST_VERSION=$(pip show pydata-sphinx-theme | grep Version | awk -F': ' '{print $2}') && \
pybabel extract . -F babel.cfg -o src/pydata_sphinx_theme/locale/sphinx.pot --keywords='_ __ l_ lazy_gettext' \
--project=pydata-sphinx-theme --copyright-holder='PyData developers' --version=$PST_VERSION"
pybabel update -i src/pydata_sphinx_theme/locale/sphinx.pot -d src/pydata_sphinx_theme/locale -D sphinx {posargs}
# add a new locale for translations based on the catalog template
# the locale needs to be given in the format of the language code
# for example: `tox -e i18n-new-locale -- ss`
[testenv:i18n-new-locale]
description = "Create a new locale based on our catalog template"
extras = {[testenv:i18n-extract]extras}
package = editable
commands =
pybabel init -i src/pydata_sphinx_theme/locale/sphinx.pot -d src/pydata_sphinx_theme/locale -l {posargs}
# compile translation catalogs to binary MO files
# tox run -e i18n-compile
[testenv:i18n-compile]
description = "Compile translation catalogs to binary MO files"
extras = {[testenv:i18n-extract]extras}
package = editable
commands =
pybabel compile -d src/pydata_sphinx_theme/locale -D sphinx