You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/community/setup.md
+32-18
Original file line number
Diff line number
Diff line change
@@ -22,10 +22,10 @@ The sections below cover the steps to do this in more detail.
22
22
23
23
## Clone the repository
24
24
25
-
First off you'll need your own copy of the `pydata-sphinx-theme` codebase.
25
+
First off you'll need your copy of the `pydata-sphinx-theme` codebase.
26
26
You can clone it for local development like so:
27
27
28
-
1.**Fork the repository** so you have your own copy on GitHub.
28
+
1.**Fork the repository**, so you have your own copy on GitHub.
29
29
See [the GitHub forking guide](https://docs.github.com/en/get-started/quickstart/fork-a-repo) for more information.
30
30
2.**Clone the repository locally** so that you have a local copy to work from:
31
31
@@ -36,14 +36,14 @@ You can clone it for local development like so:
36
36
37
37
## Install your tools
38
38
39
-
Building a Sphinx site uses a combination of Python and Jinja to manage HTML, SCSS, and Javascript.
39
+
Building a Sphinx site uses a combination of Python and Jinja to manage HTML, SCSS, and JavaScript.
40
40
To simplify this process, we use a few helper tools:
41
41
42
-
-[The Sphinx Theme Builder](https://sphinx-theme-builder.readthedocs.io/en/latest/)to automatically perform compilation of web assets.
42
+
-[The Sphinx Theme Builder](https://sphinx-theme-builder.readthedocs.io/en/latest/)compiles web assets in an automated way.
43
43
-[pre-commit](https://pre-commit.com/) for automatically enforcing code standards and quality checks before commits.
44
-
-[nox](https://nox.thea.codes/), for automating common development tasks.
44
+
-[nox](https://nox.thea.codes/) for automating common development tasks.
45
45
46
-
In particular, `nox` can be used to automatically create isolated local development environments with all of the correct packages installed to work on the theme.
46
+
In particular, `nox` can be used to automatically create isolated local development environments with all the correct packages installed to work on the theme.
47
47
The rest of this guide focuses on using `nox` to start with a basic environment.
48
48
49
49
```{seealso}
@@ -58,9 +58,9 @@ To start, install `nox`:
58
58
$ pip install nox
59
59
```
60
60
61
-
You can call `nox` from the command line in order to perform common actions that are needed in building the theme.
61
+
You can call `nox` from the command line to perform common actions that are needed in building the theme.
62
62
`nox` operates with isolated environments, so each action has its own packages installed in a local directory (`.nox`).
63
-
For common development actions, you'll simply need to use `nox` and won't need to set up any other packages.
63
+
For common development actions, you'll only need to use `nox` and won't need to set up any other packages.
64
64
65
65
### Setup `pre-commit`
66
66
@@ -116,7 +116,7 @@ Now that you've built the documentation, edit one of the source files to see how
116
116
1.**Make an edit to a page**. For example, add a word or fix a typo on any page.
117
117
2.**Rebuild the documentation** with `nox -s docs`
118
118
119
-
It should go much faster this time, because `nox` is re-using the old environment, and because Sphinx has cached the pages that you didn't change.
119
+
It should go much faster this time because `nox` is re-using the previously created environment, and because Sphinx has cached the pages that you didn't change.
120
120
121
121
## Compile the CSS/JS assets
122
122
@@ -138,15 +138,15 @@ The `sphinx-theme-builder` will bundle these assets automatically when we make a
138
138
139
139
## Run a development server
140
140
141
-
You can combine the above two actions 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.
141
+
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.
142
142
143
143
To run the development server with `nox`, run the following command:
144
144
145
145
```console
146
146
$ nox -s docs-live
147
147
```
148
148
149
-
When working on the theme, saving changes to any of these directories:
149
+
When working on the theme, making changes to any of these directories:
150
150
151
151
-`src/js/index.js`
152
152
-`src/scss/index.scss`
@@ -161,19 +161,33 @@ will cause the development server to do the following:
161
161
162
162
## Run the tests
163
163
164
-
This theme uses `pytest` for its testing, with a lightweight fixture defined
165
-
in the `test_build.py` script that makes it easy to run a Sphinx build using
166
-
this theme and inspect the results.
164
+
This theme uses `pytest` for its testing. There is a lightweight fixture defined
165
+
in the `test_build.py` script that makes it straightforward to run a Sphinx build using
166
+
this theme and inspect the results. There are also several automated accessibility checks in
167
+
`test_a11y.py`.
167
168
168
-
In addition, we use [pytest-regressions](https://pytest-regressions.readthedocs.io/en/latest/)
169
-
to ensure that the HTML generated by the theme is what we'd expect. This module
169
+
```{warning}
170
+
Currently, the automated accessibility tests check the Kitchen Sink page only.
171
+
We are working on extending coverage to the rest of the theme.
172
+
```
173
+
174
+
In addition, we use
175
+
[pytest-regressions](https://pytest-regressions.readthedocs.io/en/latest/) to
176
+
ensure that the HTML generated by the theme is what we'd expect. This module
170
177
provides a `file_regression` fixture that will check the contents of an object
171
178
against a reference file on disk. If the structure of the two differs, then the
172
179
test will fail. If we _expect_ the structure to differ, then delete the file on
173
-
disk and run the test. A new file will be created, and subsequent tests will pass.
180
+
disk and run the test. A new file will be created, and subsequent tests will
181
+
pass.
174
182
175
-
To run the tests with `nox`, run the following command:
183
+
To run the build tests with `nox`, run the following command:
The accessibility checking tools can find a number of common HTML patterns which
3
+
```{note}
4
+
April-2023: we are currently
5
+
[re-evaluating how we do accessibility checks](https://github.com/pydata/pydata-sphinx-theme/issues/1168)
6
+
and reporting, so this may change soon.
7
+
```
8
+
9
+
In general, accessibility-checking tools can find a limited number of common HTML patterns which
4
10
assistive technology can't help users understand.
5
-
We run a [Lighthouse](https://developers.google.com/web/tools/lighthouse) job in our CI/CD, which generates a "score" for all pages in our **Kitchen Sink** example documentation.
6
-
The configuration for Lighthouse is in:
7
11
8
-
-`.github/workflows/lighthouserc.json`
12
+
## Accessibility checks as part of our development process
13
+
14
+
We run a [Lighthouse](https://developers.google.com/web/tools/lighthouse) job in our CI/CD, which generates a "score" for all pages in our **Kitchen Sink** example documentation.
15
+
The configuration for Lighthouse can be found in the `.github/workflows/lighthouserc.json` file.
9
16
10
-
For more information about configuring lighthouse, see [the lighthouse documentation](https://github.com/GoogleChrome/lighthouse-ci/blob/main/docs/configuration.md).
17
+
For more information about configuring Lighthouse, see [the Lighthouse documentation](https://github.com/GoogleChrome/lighthouse-ci/blob/main/docs/configuration.md).
11
18
For more information about Accessibility in general, see [](../../user_guide/accessibility.rst).
0 commit comments