Skip to content

Latest commit

 

History

History
242 lines (163 loc) · 10.2 KB

topics.md

File metadata and controls

242 lines (163 loc) · 10.2 KB

Topic guides and how-tos

These sections cover common operations and topics that are relevant to developing this theme.

Make a release

This theme uses GitHub tags and releases to automatically push new releases to PyPI. For information on this process, see the release checklist.

Update JavaScript dependencies and their versions

The javascript dependencies for this package are defined in package.json, and broken down into a few categories like dependencies and devDependencies.

To update or add JS dependency, modify (or append to) the list of packages that are listed in each of these sections. The next time you build the documentation (either with nox or with stb), these new dependencies will be installed and bundled with the theme.

Using nox

Here are a few extra tips for using nox.

:::{seealso} The nox command line documentation has a lot of helpful tips for extra functionality you can enable with the CLI. :::

Re-install dependencies

To re-execute the installation commands, use this pattern:

$ nox -s docs -- reinstall

Or to completely remove the environment generated by nox and start from scratch:

$ rm -rf .nox/docs

Use nox with your global environment

If you'd like to use nox with your global environment (the one from which you are calling nox), you can do so with:

$ nox --force-venv-backend none

# alternatively:
$ nox --no-venv

Using none will re-use your current global environment. See the nox documentation for more details.

Using pre-commit

Here are a few tips for using pre-commit:

Skip the pre-commit checks

Run the following command:

$ git commit --no-verify

Run pre-commit on all files

By default, pre-commit will run its checks on files that have been modified in a commit. To instead run it on all files, use this command:

$ pre-commit run --all-files

# Alternatively
$ pre-commit run -a

Web assets (CSS/JS/Fonts)

This theme includes several web assets to ease development and design. The configuration for our asset compilation is in webpack.config.js.

Compile and bundle assets

When assets are compiled, static versions are placed in various places in the theme's static folder:

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/static

For many assets, a <hash> is generated and appended to the end of its reference in the HTML templates of the theme. This ensures the correct asset versions are served when viewers return to your site after upgrading the theme.

To compile the assets and bundle them with the theme, run this command:

$ nox -s compile

Styles (SCSS) and Scripts (JS)

There are two relevant places for CSS/JS assets:

  • src/pydata_sphinx_theme/assets/styles has source files for SCSS assets. These will be compiled to CSS.
  • src/pydata_sphinx_theme/assets/scripts has source files for JS assets. These will be compiled to JS and import several vendored libraries (like Bootstrap).
  • src/pydata_sphinx_theme/theme/pydata_sphinx_theme/static has compiled versions of these assets (e.g. CSS files). This folder is not tracked in .git history, but it is bundled with the theme's distribution.

Vendored scripts

We vendor several packages in addition to our own CSS and JS. For example, Bootstrap, JQuery, and Popper. This is configured in the webpack.config.js file, and imported in the respective SCSS or JS file in our assets folder.

FontAwesome icons

Three "styles" of the FontAwesome 5 Free icon font are used for {ref}icon links <icon-links> and admonitions, and is the only vendored font.

  • It is managed as a dependency in package.json
  • Copied directly into the site statics at compilation, including licenses
  • Partially preloaded to reduce flicker and artifacts of early icon renders
  • Configured in webpack.config.js

Jinja macros

Our Webpack build generates a collection of Jinja macros in the static/webpack-macros.html file.

These macros are imported in the main layout.html file, and then inserted at various places in the page to link the static assets.

Some of the assets are "preloaded", meaning that the browser begins requesting these resources before they're actually needed. In particular, our JavaScript assets are preloaded in <head>, and the scripts are actually loaded at the end of <body>.

Accessibility checks

The accessibility checking tools can find a number of common HTML patterns which assistive technology can't help users understand.

In addition to Lighthouse in CI, the pa11y stack is installed as part of the development environment.

The key components are:

  • pa11y which uses a headless browser to analyze an HTML page with a configurable set of rules based on publish standards
  • Pa11y-CI runs pa11y on multiple pages
  • pa11y-reporter-html generates some nice HTML reports, suitable for review

:::{note} Presently, the default pa11y ruleset, WCAG2AA is used, a subset of the Web Content Accessibility Guidelines. The Quick Reference may provide lighter reading. :::

Errors in CI/CD and what to do

We have a list of known accessibility problems in the file docs/scripts/a11y-roadmap.txt. This contains a list of errors that we aim to fix in the future, and that do not cause tests to fail.

When a pa11y accessibility audit is run in our CI/CD, it checks for any errors that are not on this list, and if it finds them it will cause the job to error.

When you see an error in your CI/CD job, look at the logs under the Run accessibility audit job. You should see an output that looks like this:

JSON: /tmp/pa11y/pa11y-864/pa11y-ci-results.json
Roadmap: /home/runner/work/pydata-sphinx-theme/pydata-sphinx-theme/docs/a11y-roadmap.txt
not on roadmap:
  WCAG2AA.Principle2.Guideline2_4.2_4_1.G1,G123,G124.NoSuchID: 4
on roadmap:
  WCAG2AA.Principle1.Guideline1_3.1_3_1.H39.3.LayoutTable: 1
  WCAG2AA.Principle1.Guideline1_3.1_3_1.H43,H63: 1
  WCAG2AA.Principle1.Guideline1_3.1_3_1.H43.HeadersRequired: 1
  WCAG2AA.Principle1.Guideline1_4.1_4_3.G18.Fail: 1828
  WCAG2AA.Principle3.Guideline3_2.3_2_2.H32.2: 48
  WCAG2AA.Principle4.Guideline4_1.4_1_2.H91.A.EmptyNoId: 9
passed: false
total errors: 1892

The problems that caused an error are in the not on roadmap section. Anything that is "not on the roadmap" is an error we have unexpectedly introduced in the PR. These should be identified and fixed.

Fix accessibility errors

We keep a list of known accessibility issues in the {download}accessibility roadmap <../scripts/a11y-roadmap.txt>. These are issues which are currently flagged by the toolset, but that have not yet been fixed.

To start working on one of the accessibility roadmap items, comment out one of the lines in docs/a11y-roadmap.txt, and re-run the audit to establish a baseline.

Then, fix the issue in either the HTML templates, CSS, or python code, and re-run the audit until it is fixed.

Run an accessibility audit locally

To run the accessibility problem finder locally:

$ nox -s compile  # Compile the theme assets
$ nox -s docs  # Build the documentation
$ python docs/scripts/a11y.py  # Run a helper script for an accessibility audit

The output of the last command includes:

  • a short summary of the current state of the accessibility rules we are trying to maintain
  • local paths to JSON and HTML reports which contain all of the issues found

Update support for new Sphinx versions

This theme does not pin the upper version of Sphinx that it supports, but there may be changes that need to happen when Sphinx releases a new version. As a general rule, we try to support new major Sphinx versions within 6 months of its release.

Here's a list of things to check when Sphinx releases a new version:

Update our kitchen sink documents

The kitchen sink reference is for demonstrating as much syntax and style for Sphinx builds as possible. It is copied directly from the sphinx-themes.org documentation so that we use standardized reference docs compared with other communities. The source files for these pages are stored in the sphinx-themes.org repository.

If you'd like to update our local files with any changes that have been made to the sphinx-themes.org files, simply copy/paste those changes into our local files and make a commit.

Here's a list of our pages and where they come from in sphinx-themes.org:

:::{note} To demonstrate extra styles and syntax that is not in the Kitchen sink, use the Theme Elements reference. :::