This project follows the Read the Docs code of conduct. If you are not familiar with our code of conduct policy, take a minute to read the policy before starting with your first contribution.

Modifying the theme

The styles for this theme use SASS and a custom CSS framework called Wyrm. We use Webpack and node-sass to build the CSS. Webpack is used to watch for changes, rebuild the static assets, and rebuild the Sphinx demo documentation.


The installation of Node is outside the scope of this documentation. You will need Node version 10+ in order to make changes to this theme.

Set up your environment

  1. Install Sphinx and documentation build dependencies.

    $ pip install -e '.[dev]'
  2. Install Webpack, node-sass, and theme dependencies locally.

    $ npm install

Making changes

Changes to the theme can be compiled and tested with Webpack:

$ npm run dev

This script will do the following:

  1. Install and update any dependencies.

  2. Build the static CSS from SASS source files.

  3. Build the demo documentation.

  4. Watch for changes to the SASS files and documentation and rebuild everything on any detected changes.

Alternatively, if you don’t need to watch the files, the release build script can be used to test built assets:

$ npm run build


Translations are managed using Transifex. You can join any of the existing language teams or request a new language is added to the project. For more information on our translation standards, see our docs on Internationalization

Periodically, core team should update the translation files outside our normal releases. Someone from the core team, with write access to Transifex, should run the following:

$ python update_translations

This will extract new messages, upload the messages to Transifex, and will update our local translation files. Changes can be checked in to a branch and put up for review.

Releasing the theme

To release a new version of the theme, core team will take the following steps:

  1. Bump the version by running bump2version [major|minor|patch|dev]. This will automatically increase the correct part(s) of the version number, you do not need to specify the exact version number. We follow semver and PEP440 (with regards to alpha release and development versions). The version increment should reflect these releases and any potentially breaking changes.

  2. New versions are by default alpha releases. If this is a release candidate, run bump2version --allow-dirty releast to update the release to an rc release. If this is a final release, run the command again.

  3. Update the changelog (docs/changelog.rst) with the version information.

  4. Run python update_translations to compile new translation files and update Transifex.

  5. Run python build to rebuild all the theme assets and the Python package.

  6. Commit these changes.

  7. Tag the release in git: git tag $NEW_VERSION.

  8. Push the tag to GitHub: git push --tags origin.

  9. Upload the package to PyPI:

    $ rm -rf dist/
    $ python sdist bdist_wheel
    $ twine upload --sign --identity dist/*