napari-sphinx-theme

A Sphinx theme with the look and feel of napari based on the awesome pydata-sphinx-theme.

Description

Since the napari-sphinx-theme extends the pydata-sphinx-theme, the configurations and affordances provided by the PyData Sphinx Theme can be used within the napari docs.

Installation

After creating a virtual environment, install the theme in editable mode:

python -m pip install -e . --group dev

For local development with uv, the shortest path is:

uv sync

Theme development

Configuration options

Modify options in theme.conf to customize the pydata-sphinx-theme for napari.

Styling (CSS)

Styling settings and napari's custom CSS is found in the static/css/napari-sphinx-theme.css file.

The styling of code snippets is configured in napari_sphinx_theme/napari_code_theme.py.

Templates (HTML)

To modify page layouts, modify the html template files in the napari_sphinx_theme and napari_sphinx_theme/partials directories.

Build demo docs and theme changes

To build the demo site found in this repo, run from the repository root:

uv run make docs

To start a live preview that rebuilds when you edit the docs or theme files, run:

uv run make docs-live

The live server opens a browser automatically and watches both docs/ and napari_sphinx_theme/. CSS, templates, and theme configuration changes are displayed automatically without having to restart the live server.

Build a distribution wheel for local testing

To build a wheel locally, run:

uv run make build

Use the demo site to manually test changes to styles and page layouts.

The napari website

The napari website is built using the napari docs repo. The styling of the website is based on this theme. Install this theme as a dependency in the napari docs repo.

To modify the website's styling, minor changes to CSS can be made in the docs repo. More significant changes, such as those that may impact the entire website and docs, should be made here.