Contribution guides

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. Follow these steps to make a release:

• Familiarize yourself with our Release guidelines and decide if it is time for a release.

• Copy the release infrustructions in the release checklist.

• Paste them into a new issue to coordinate the release.

• Follow the 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.

See also

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 6 Free icon font are used for 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. We run a Lighthouse job in our CI/CD, which generates a “score” for all pages in our Kitchen Sink example documentation. The configuration for Lighthouse is in:

• .github/workflows/lighthouserc.json

For more information about configuring lighthouse, see the lighthouse documentation. For more information about Accessibility in general, see Accessibility.

Supporting new Python versions

For releases of Python, we aim to follow this approach[1]:

For a new major/minor release of this theme, we support any minor Python versions released in the last 3.5 years (42 months), as defined in the EOL schedule for Python[2].

We define “support” as testing against each of these versions, so that users can be assured they will not trigger any bugs.

For example, if we made a minor release tomorrow, we’d look at the EOL schedule for Python and support all of the versions that fall within a 3.5 year window.

Supporting new Sphinx versions

For supporting versions of Sphinx, we aim to follow this approach:

We support the latest released version of Sphinx that is older than 6 months. We unofficially support earlier released versions of Sphinx, but may increase the lower-bound in our dependency pin without warning if needed[2].

When a new pre-release of Sphinx is released, we should follow these steps:

• Ensure that our tests are passing. We run our tests with any pre-releases of Sphinx, so we can test major errors quickly and make the necessary changes.

• Look at the Sphinx Changelog and make sure there are no changes that might break things that aren’t captured by our tests.

• Look at the deprecated API changes and make sure there are no changes that might break things that aren’t captured by our tests.

• Look at the docutils changelog in case there’s a new docutils version supported that breaks something.

Note

This theme does not pin the upper version of Sphinx that it supports. If a Sphinx release causes major breaking changes for our users, and we do not have the capacity to update our code and release a fix, we may temporarily pin the upper bound of Sphinx we support until this is fixed.

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.

To update the kitchen sink source files, there is a helper Python script that will loop through the known kitchen sink files and copy over the latest text. To use it, run the following from the root of the repository:

Update the example gallery

This theme’s documentation contains a gallery of sites that use this theme for their documentation. The images are automatically generated during ReadTheDocs builds, but are not automatically generated on local or test builds (to save time).

If you build the documentation locally without first generating these images you may get Sphinx warnings or errors, but this should be fine as long as the images build on ReadTheDocs tests.

If you’d like to build these images locally to preview in the theme, follow these steps:

1. Install playwright and the Chromium browser add-on:

   $ pip install playwright
   $ playwright install chromium
   

2. Execute the gallery generation script from the repository root:

   $ python ./docs/scripts/generate_gallery_images.py
   

Note

The newly generated images will be pushed to the distant repository.

Update JavaScript dependencies and their versions

There are two kinds of dependency definitions in this theme:

• package.json contains the base dependencies for this theme. They are broken down into a few categories like dependencies and devDependencies. It is edited by the maintainers.

• package-lock.json contains the complete frozen dependency chain for this theme, including all sub-dependencies of our base dependencies. It is automatically generated.

To update or add a JS dependency, follow these steps:

1. Edit package.json by adding or modifying a dependency.

2. Re-generate package-lock.json in order to create a new set of frozen dependencies for the theme. To do this, run the following command from the Sphinx Theme Builder.

   stb npm install --include=dev
   

3. Commit both files to the repository. When new people pull in the latest commits, their npm environment will automatically update according to the new lockfile.

PyData package support

This theme is designed by and for the PyData community, and so there are a few places where we special-case support for packages in this community.

We define CSS rules that ensure PyData content in Sphinx looks reasonable on both light and dark themes. If we hear reports from maintainers that we could change something in this theme that would make their documentation look better, and if this change is sustainable for us, then we should do so.

We store our PyData-specific SCSS in two relevant files, both in the src/pydata_sphinx_theme/assets/styles/ folder:

• extensions/_execution.scss - styles for Sphinx libraries that execute and insert code into the documentation. For example, MyST-NB, Jupyter Sphinx, and the Matplotlib plot directive. Most PyData support should go here via generic improvements that all packages benefit from.

• extensions/_pydata.scss - styles for specific libraries in the PyData ecosystem. In general we should try to keep this minimal because it is mostly special-casing single library quirks.

Ignore formatting commits with git blame

When making commits that are strictly formatting/style changes (e.g., after running a new version of black or running pyupgrade after dropping an old Python version), add the commit hash to .git-blame-ignore-revs, so git blame can ignore the change.

For more details, see:

• https://git-scm.com/docs/git-config#Documentation/git-config.txt-blameignoreRevsFile

• https://github.com/pydata/pydata-sphinx-theme/pull/713

The gallery-grid directive

There are a few places where we use sphinx-design to generate “galleries” of grids with structured text and images. We’ve created a little Sphinx directive to make it easier to repeat this process in our documentation and to avoid repeating ourselves too much. It is located in the docs/scripts/ folder in a dedicated module, and re-used throughout our documentation.

Page-level configuration

In some areas we support page-level configuration to control behavior on a per-page basis. Try to make this configuration follow the html_theme_options structure of our configuration as much as possibl. Begin them with html_theme, and separate “nested” configuration sections with periods (.). This is similar to how the TOML language defines nested configuration.

For example, to remove the secondary sidebar, we use a page metadata key like this:

:html_theme.sidebar_secondary.remove: true

Note how the period naturally separates nested sections, and looks very similar to what we’d expect if we put this in a Python dictionary in conf.py:

html_theme_options = {
   "sidebar_secondary": {"remove": "true"}
}

---

[1]

Our support for Python versions is inspired by NEP 029.

[2] (1,2)

These policies are goals, but not promises. We are a volunteer-led community with limited time. Consider these sections to be our intention, but we recognize that we may not always be able to meet these criteria if we do not have capacity to do so. We welcome contributions from others to help us more sustainably meet these goals!