Development

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.

Start with make

# show all available tasks
make

Install requirements and fulfill Python and Node demands (repeatable)

make setup

When doing frontend development compile your changes at any time

make frontend

Build and install the package

make install

Build and install the package for development

make install-for-development

Don’t forget to update the docs. Render the documentation

make docs

Serve build docs locally

make serve

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

make test

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 make installed

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 .venv 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:

npm install

Now, build the frontend (this compiles the CSS and JavaScript). Re-run this whenever you edit .scss or .js files.

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 ./docs/_build/.

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 .rst or .md file in the ./docs/ folder.

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:

flake8 .

Example Pages

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.

Javascript package management

Use npm for package management.