---
# System prepended metadata

title: 'PRD: sphinx theme for [napari.org](http://napari.org/)'
tags: [PRD]

---

---
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. *
