If you find errors, omissions, inconsistencies or other things that need improvement, please create an issue or a pull request at Contributions are always welcome!

Development Installation

Instead of pip-installing the latest release from PyPI, you should get the newest development version from Github:

git clone
cd sphinxcontrib-katex
python develop --user

This way, your installation always stays up-to-date, even if you pull new changes from the Github repository.

If you prefer, you can also replace the last command with:

pip install --user -e .

… where -e stands for --editable.

Building the Documentation

If you make changes to the documentation, you can re-create the HTML pages using Sphinx. You can install it and a few other necessary packages with:

pip install -r doc/requirements.txt --user

To create the HTML pages, use:

python build_sphinx

The generated files will be available in the directory build/sphinx/html/.

It is also possible to automatically check if all links are still valid:

python build_sphinx -b linkcheck

Running the Tests

You’ll need pytest for that. It can be installed with:

pip install -r tests/requirements.txt --user

To execute the tests, simply run:

python -m pytest

Creating a New Release

New releases are made using the following steps:

  1. Bump version number in sphinxcontrib/
  2. Update NEWS.rst
  3. Commit those changes as “Release x.y.z”
  4. Create an (annotated) tag with git tag -a x.y.z
  5. Clear the dist/ directory
  6. Create a source distribution with python sdist
  7. Create a wheel distribution with python bdist_wheel --universal
  8. Check that both files have the correct content
  9. Upload them to PyPI with twine: twine upload dist/*
  10. Push the commit and the tag to Github and add release notes containing a link to PyPI and the bullet points from NEWS.rst
  11. Check that the new release was built correctly on RTD, delete the “stable” version and select the new release as default version