---
tags: PRD
---

# PRD: sphinx theme for [napari.org](http://napari.org/)

a pip-installable theme to simplify docs building for napari contributors

- Team: napari docs working group
- Contributors: Justin, Lia, Jeremy, Melissa
- Resources: [Designs],
- Status: Draft / Problem Review / **Solution Review** / Launch Review / Launched
- Last Updated: Tuesday, Jan 5, 2022

* * *

## Problem alignment

The [napari.org](http://napari.org/) website features a custom theme to support a consistent look-and-feel with the napari hub, however, the current process for building the [napari.org](http://napari.org/) site is too complex for documentation contributors to easily preview their changes locally.

### High Level Approach

To simplify the build process, we are going to release the [napari.org](http://napari.org/) theme as a pip-installable sphinx theme and rely on the sphinx build process to render the [napari.org](http://napari.org/) website.

### Goals

1. Provide a sphinx theme for use on the [napari.org](http://napari.org/) project
2. Enable other tools in the napari ecosystem ([magicgui](https://napari.org/magicgui/), npe2, [plugins](https://cellpose-napari.readthedocs.io/en/latest/)) to use the theme as well

### Non-goals

1. Provide a general purpose reusable sphinx theme for any Python developer

## Solution Alignment

### Key Features

Plan of record

1. Theme will be available on PyPI and installable through standard sphinx configuration (specified in requirements, then refered by name in `conf.py`
2. Theme will enable documentation developers to customize the logo and other specialized assets (such as Twitter handle or support site links) through configuration options in `conf.py`, but any changes to color, typography, etc will require custom CSS.
3. Theme will support JupyterBook by providing support for the custom sphinx extensions that come bundled with JupyterBook:
1. **[MyST-NB](https://myst-nb.readthedocs.io/)** - Functionality for reading in Jupyter Notebooks in Sphinx, as well as executing them.
2. **[sphinx panels](https://sphinx-panels.readthedocs.io/en/latest/)** - Provide Sphinx directives for “Bootstrap Cards” that are used throughout the Jupyter Book docs.
4. Theme will support additional sphinx extensions used on [napari.org](http://napari.org/) which generate custom HTML elements, including
1. [viewcode](https://www.sphinx-doc.org/en/master/usage/extensions/viewcode.html)
2. [autodoc](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html)
3. [autosummary](https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html)
4. [sphinx-tabs](https://github.com/executablebooks/sphinx-tabs)
5. [sphinx-galley](https://sphinx-gallery.github.io/stable/index.html)

### Key Flows

A plugin developer wants to use the napari sphinx theme for their docs

* add `napari-sphinx-theme` to the requirements for their docs
* read the documentation on the theme and add relevant configuration variables to their `conf.py`
*

## Launch Plan

The launch will begin with a release of v0.1.0 and a rollout for [napari.org](http://napari.org/), followed by a v0.2.0 release which provides support

### Key Milestones

|TARGET DATE |OWNER |MILESTONE |DESCRIPTION |
|--- |--- |--- |--- |
|2022-01-26 |Jeremy |Tech spec |Plan for implementation, incl starting point, presented to docs WG |
|2022-02-02 |Melissa |Revert to Furo |Revert napari.org theme to Furo with simple build process |
|2022-02-22 |Jeremy |QA & Testing |Theme available for QA & testing by napari community. v0.1.0rc1 |
|2022-02-08 |Justin |Launch on napari.org |Approval of new theme from napari community. release v0.1.0 |
|2022-02-22 |Justin |Release for community |v.0.2.0, usage docs on Github README |

## Appendix

### Open Questions

*Track open questions and answers here. *