🔨 Development

Project structure

confirm/sphinx/
├── __init__.py              # Extension: enables the theme, extensions and defaults
├── config.py                # Default settings, based on the CI variables
├── defaults.py              # Removed module, raises an upgrade hint
└── theme/
    ├── __init__.py          # Registers the theme with Sphinx (entry point)
    ├── theme.toml           # Theme definition (inherits from Furo)
    ├── macros.html          # Template helpers
    ├── base.html            # Furo override: logo prefetch links
    ├── sidebar/
    │   └── brand.html       # Furo override: sidebar logos
    └── static/css/
        ├── theme.css        # Layout, typography and component overrides
        ├── vars.css         # Colour and font variables (light mode)
        └── vars-dark.css    # Colour variables (dark mode)

Set up your environment

Create a virtual environment and install the package in editable mode:

make venv
source .venv/bin/activate
make develop

Preview your changes

These docs use the theme itself, so they’re the quickest way to check your changes:

make docs

The output is in build/docs. For a live preview, run:

make autodocs

It opens the docs on http://localhost:8888, and rebuilds them whenever you change the docs or the source code.

Change the styles

  • Change colours in vars.css and vars-dark.css. Keep both files in sync, and use the confirm IT palette variables (--cd-*) instead of hard-coded colours.

  • Change layout, typography and components in theme.css.

  • Stick to the Colours, Typography and Layout & grid guidelines in the handbook.

  • Check your changes on the 🌈 Showcase in light and dark mode.

Change the defaults

Parts of 🎛️ Defaults are included straight from confirm/sphinx/config.py. The included code blocks are wrapped in marker comments:

# [docs:extensions]
EXTENSIONS = (
    ...
)
# [/docs:extensions]

  • Keep the markers when you change the code, otherwise the code block disappears from the docs and Sphinx warns “pattern not found”.

  • Keep the inline comments up to date, they’re the documentation of each line.

Run the tests

make test

This validates the commit messages and runs isort, pycodestyle and pylint with our shared linter configs.

Release

The version comes from the Git tag (setuptools_scm). The GitLab pipeline builds and publishes the package and the docs, based on our shared python-library CI template.

Important

The minimal Sphinx version is defined twice: in pyproject.toml and in confirm/sphinx/theme/__init__.py. Update both when you raise it.