For local development you need a system with Node v18.x, Python3, and Git. It is strongly recommended to use a Python virtual environment (venv). The build process derives the version from repository data, so it’s necessary to clone the repository and not just download a single snapshot.
Mac or Linux¶
These steps require having
make installed. If the first command below
produces an error, you can follow the steps below in the Windows section.
# show all available tasks make
Install requirements and fulfill Python and Node demands (repeatable)
When doing frontend development compile your changes at any time
Build and install the package
Build and install the package for development
Don’t forget to update the docs. Render the documentation
Serve build docs locally
Check the Python code. The CI workflow requires
lint-minimal to succeed
# for local use make lint # used in the workflow make lint-minimal
Run Python unit tests
Rebuild and install from Python wheel package
make install # then verify the module can be imported and used make test-import
To find out whether the created wheel package passes the twine check test and can be uploaded to PyPi run
make build test
Windows, or systems without
Windows does not have
make therefore we must run the commands directly
rather than using the shortcuts in the Makefile. Assume the commands below are
all run in PowerShell. These instructions will also work on Mac or Linux without
make installed as well.
First, be sure to install Python 3, and Node 18. fnm is really useful for managing multiple versions of Node on Windows.
Make a Python virtual environment. Let’s make it in a folder called
which will be ignored by git.
# Create the venv python -m venv ./.venv/ # Activate it (PowerShell) ./.venv/Scripts/Activate.ps1 # Install dependencies pip install -r requirements-dev.txt
Install the the NPM dependencies:
whenever you edit
npm run frontend
To test out the sphinx theme, build the project’s own documentation using the
theme! The command below tells Sphinx to build the
./docs/ folder as HTML,
and put the output HTML files in
sphinx-build -M html ./docs/ ./docs/_build/
If you see any red errors in the console, that would most likely be related to
a syntax error in a
.md file in the
To browse the docs you just built, fire up a simple web server using Python:
python -m http.server -d ./docs/_build/html/
Now go to http://localhost:8000/ in your browser.
If you make any changes to the Python code, you’ll want to run the linters to check for errors:
When working on the theme it is often going to be helpful to know the impact of your changes. The examples section should be helpful for this.
When you are adding new elements or styles that are not part of the examples, please make sure to add them.
npm for package management.