This guide will teach you how to submit new documents to napari’s usage documentation.
A GitHub account
A clean conda environment with napari docs dependencies installed
You can install these with
pip install "napari[docs]"
These dependencies will allow you to preview your document locally, as it would appear on
They will also install
jupytext, which you will need to contribute documents containing code or viewer interactions
0. Before you start¶
If you’d like to contribute a brand new document to our usage section, it might be worth opening an issue on our repository first to discuss the content you’d like to see and get some early feedback from the community. The napari team can also suggest what type of document would be best suited, and whether there are already existing documents that could be expanded to include the content you think is lacking.
Examples of documents you might want to contribute are:
napari/docs/guides): in depth content about napari architecture, development choices and some complex features
napari/docs/tutorials): detailed, reproducible step by step guides, usually combining multiple napari features to complete a potentially complex task
napari/docs/howtos/): simple step by step guides demonstrating the use of common features
Getting started (in
napari/docs/tutorials/fundamentals): these documents are a mix of tutorials and how-tos covering the fundamentals of installing and working with napari for beginners
Got materials for a workshop?
If you already have teaching materials e.g. recordings, slide decks or jupyter notebooks hosted somewhere, you can add links to these on our napari workshops page.
If you are writing a document whose content is mostly text, you can write a plain markdown document and skip straight to Step #3 - Update TOC. If you are writing a how-to guide or tutorial that requires executing code or working with the napari viewer, follow the steps below to prepare your document.
Prerequisites for contributing documentation with code¶
Jupyter notebook installed
Familiarity with Jupyter notebooks (code cells and markdown cells)
Familiarity with using napari through a Jupyter notebook
1. Download our template¶
Our goal is that all tutorials and how-tos are easily downloadable and executable by our users. This helps ensure that they are reproducible and makes them easier to maintain. We therefore provide a notebook template for our documents.
Jupyter notebooks are a great option for our documents, because they allow you to easily combine code and well formatted text in markdown. However, their raw JSON format is not great for version control, so we use MyST Markdown documents in our repository and on napari.org.
Fork and clone our repository, and make a copy of
You can edit the template directly in Jupyter notebook, or in your preferred text editor.
Already have a notebook?
If you have an existing
.ipynb Jupyter notebook that you’d like to contribute, you can convert it to MyST markdown
and then edit the
.md file to prepare it for contributing.
jupytext your-notebook.ipynb --to myst to create a new file,
your-notebook.md. Edit this file to
include the relevant sections from the docs template.
2. Write your document¶
Follow the template to write your document. Inside the template you’ll also find handy tips for taking screenshots of the viewer, hiding code cells, using style guides and what to include in the required prerequisites section.
3. Update TOC¶
Add your document to the correct folder based on its content (see the list above for common locations), and update
If you’re adding a document
to an existing group, simply add a new
- file: entry in the appropriate spot. For example, if I wanted to add
progress_bars.md how to guide, I would place it in
napari/docs/howtos and update
_toc.yml as below:
- file: howtos/index subtrees: - titlesonly: True entries: - file: howtos/layers/index subtrees: - titlesonly: True entries: - file: howtos/layers/image - file: howtos/layers/labels - file: howtos/layers/points - file: howtos/layers/shapes - file: howtos/layers/surface - file: howtos/layers/tracks - file: howtos/layers/vectors - file: howtos/connecting_events - file: howtos/napari_imageJ - file: howtos/docker - file: howtos/perfmon - file: howtos/progress_bars # added
To create a new subheading, you need a
subtrees entry. For example, if I wanted to add
to a new
geosciences subheading in tutorials, I would place my documents in a new folder
together with an
index.md that describes what these tutorials would be about, and then update
_toc.yml as below:
- file: tutorials/index subtrees: - entries: - file: tutorials/annotation/index subtrees: - entries: - file: tutorials/annotation/annotate_points - file: tutorials/processing/index subtrees: - entries: - file: tutorials/processing/dask - file: tutorials/segmentation/index subtrees: - entries: - file: tutorials/segmentation/annotate_segmentation - file: tutorials/tracking/index subtrees: - entries: - file: tutorials/tracking/cell_tracking - file: tutorials/geosciences/index # added subtrees: # added - entries: # added - file: tutorials/geosciences/geo_tutorial1 # added - file: tutorials/geosciences/geo_tutorial2 # added
4. Preview your document¶
Once you’ve added your document to the
docs folder and updated the
_toc.yml, you can preview the website
locally by running
make docs from the root of
napari repository (assuming you’ve installed the docs prerequisites).
The rendered HTML will be placed in
index.html in this folder and drag it
into a browser to preview the website with your new document.
5. Submit your pull request¶
Once you have written and previewed your document, it’s time to open a pull request to napari’s main repository and contribute it to our codebase. If you’ve never opened a Pull Request, you may find this guide useful. You can also reach out to us on zulip for assistance!
Not sure where to place your document or update
_toc.yml? Make a best guess and open the pull request - the napari team will
help you edit your document and find the right spot!