Update contrbution docs

.github/actions/set-dev-env/action.yml

@@ -21,8 +21,10 @@ runs:
         cache: "pip"
         cache-dependency-path: "pyproject.toml"
         allow-prereleases: true
+
     - run: python -Im pip install tox-uv
       shell: bash
+
     # waiting for https://github.com/nikeee/setup-pandoc/pull/8
     # using 12rambau fork until then
     - name: "Install pandoc 📝"

docs/community/setup.md

@@ -10,8 +10,8 @@ If you are comfortable with and prefer a more manual setup refer to the [](topic
 We follow a [typical GitHub workflow](https://guides.github.com/introduction/flow/)
 of:
 
-- create a personal fork of this repo
-- create a branch
+- create a personal fork and local clone of this repo
+- create a branch for your contribution
 - open a pull request
 - fix findings of various linters and checks
 - work through code review
@@ -38,7 +38,7 @@ You can clone it for local development like so:
 
 ## Install your tools
 
-Building a Sphinx site uses a combination of Python and Jinja to manage HTML, SCSS, and JavaScript.
+Building a Sphinx site uses a combination of Python and `Jinja` to manage `HTML`, `scss`, and `JavaScript`.
 To simplify this process, we use a few helper tools:
 
 - [The Sphinx Theme Builder](https://sphinx-theme-builder.readthedocs.io/en/latest/) compiles web assets in an automated way.
@@ -62,7 +62,7 @@ $ pip install tox
 ```
 
 You can call `tox` from the command line to perform common actions that are needed in building the theme.
-`tox` operates with isolated environments, so each action has its own packages installed in a local directory (`.tox`).
+`tox` operates with isolated environments, so each action has its packages installed in a local directory (`.tox`).
 For common development actions, you'll only need to use `tox` and won't need to set up any other packages.
 
 ### Setup `pre-commit`
@@ -109,7 +109,7 @@ $ tox run -e docs-dev
 
 This will install the necessary dependencies and build the documentation located in the `docs/` folder.
 The generated documentation will be placed in a `docs/_build/html` folder.
-If the docs have already been built, it will only re-build the pages that have been updated.
+If the docs have already been built, it will only rebuild the pages that have been updated.
 You can open one of the HTML files there to preview the documentation locally.
 
 Alternatively, you can invoke the built-in Python [http.server](https://docs.python.org/3/library/http.server.html#module-http.server) with:
@@ -137,7 +137,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 -e run compile
+$ tox run -e compile
 ```
 
 This will compile all assets and place them in the appropriate folder to be used with documentation builds.
@@ -154,7 +154,7 @@ You can combine the above two actions (build the docs and compile JS/CSS assets)
 To run the development server with `tox`, run the following command:
 
 ```console
-$ tox -e run docs-live
+$ tox run -e docs-live
 ```
 
 When working on the theme, making changes to any of these directories:
@@ -196,24 +196,26 @@ To run the build tests with `tox`, run the following command:
 
 ```console
 # this will compile the assets and run the tests (with test coverage)
-$ tox -e run compile,tests
+# note the use of the `-m` flag vs. other commands in this guide
+$ tox run -m tests
 
-# to run the tests without pre-compiling the assets and without coverage (for example if you recently compiled the assets)
-$ tox -e run tests-no-cov
+# to run the tests only without pre-compiling the assets and without coverage (for example if you recently compiled the assets)
+$ tox run -e tests-no-cov
 ```
 
 To run the accessibility checks:
 
 ```console
-$ tox -e run compile,docs, a11y-tests
+# this will compile the assets, build the documentation, and run the accessibility tests
+$ tox run -m a11y
 
 # to run the tests without pre-compiling the assets and without re-building the docs (for example if you recently compiled the assets or built the docs)
-$ tox -e run a11y-tests
+$ tox run -e a11y-tests
 ```
 
-## GitHub codespaces
+## GitHub Codespaces
 
-If you have good internet connectivity and want a temporary set-up, it is often faster to work on PyData Sphinx Theme
-in a Codespaces environment. Once your Codespaces instance is set up, you can run the `tox` commands above to build
-the documentation, compile the assets, and run the tests.
+If you have good internet connectivity and want a temporary set-up, it is often faster to work on the PyData Sphinx Theme
+in a Codespaces environment.
+Once your Codespaces instance is set up, you can run the `tox` commands above to build the documentation, compile the assets, and run the tests.
 For documentation on how to get started with Codespaces, see [the Codespaces documentation](https://docs.github.com/en/codespaces).

docs/community/topics/accessibility.md

@@ -6,8 +6,8 @@ April-2023: we are currently
 and reporting, so this may change soon.
 ```
 
-In general, accessibility-checking tools can find a limited number of common HTML patterns which
-assistive technology can't help users understand.
+In general, accessibility-checking tools can find a limited number of common HTML patterns that assistive technology
+can't help users understand.
 
 ## Accessibility checks as part of our development process
 

docs/community/topics/manual-dev.md

@@ -2,7 +2,8 @@
 
 # Set up a manual development environment
 
-If you prefer not to use automation tools like `tox`, or want to have more control over the specific version of packages that you'd like installed, you may set your local development environment manually.
+If you prefer not to use automation tools like `tox`, or want to have more control over the specific version of packages that you'd like installed,
+you may set your local development environment manually.
 
 To do so, follow the instructions on this page.
 

tests/README.md

@@ -18,7 +18,7 @@ This directory contains the Python tests for the theme. These tests are built wi
   In contrast to the build test suite, the accessibility suite checks components as
   they appear in the browser, meaning with any CSS and JavaScript applied. It does
   this by building the PyData Sphinx Theme docs, launching a local server to the
-  docs, then checking the "Kitchen Sink" example pages with
+  docs, and then checking the "Kitchen Sink" example pages with
   [Playwright](https://playwright.dev), a program for developers that allows
   loading and manipulating pages with various browsers, such as Chrome (chromium),
   Firefox (gecko), Safari (WebKit).
@@ -27,17 +27,17 @@ The ["Kitchen Sink" examples](https://pydata-sphinx-theme.readthedocs.io/en/stab
 are taken from [sphinx-themes.org](https://sphinx-themes.org/) and showcase
 components of the PyData Sphinx Theme, such as admonitions, lists, and headings.
 
-## visually debugging the test pages
+## Visually debugging the test pages
 
 It can be useful to build and inspect the test pages in the browser.
 
-By default `nox -s test` will build the html in a temporary directory.
+By default, `tox run -m tests` (or any other `tox` command that runs our tests) will build the HTML in a temporary directory.
 You can change this by using the `PST_TEST_HTML_DIR` environment variable.
 
 For example:
 
-```
-$ PST_TEST_HTML_DIR=./debug-test-theme/ nox -s test
+```bash
+$ PST_TEST_HTML_DIR=./debug-test-theme/ tox run -m tests
 ```
 
-Will save all the generated html in the folders `./debug-test-theme/<test-name>/<site-name>`
+Will save all the generated HTML in the folders `./debug-test-theme/<test-name>/<site-name>`

tox.ini

@@ -2,13 +2,20 @@
 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
+# .github/actions/set-dev-env/action.yml (default Python version)
 env_list =
     lint,
     compile,
     py312-docs,
     py312-tests,
-    a11y-tests,
+    a11y-tests
+
+# convenience label for running tests with a given Python version, aimed at 
+# helping contributors run tests locally
+# tox run -m tests
+labels = 
+    tests = compile, py312-tests
+    a11y = compile, py312-docs, a11y-tests
 
 # general tox env configuration
 # these can be run with any py3{9,12} version