napari docs

This repository contains the sources for the napari documentation. This includes tutorials, how-tos and other narrative documentation. The autogenerated API documentation is extracted from the source code docstrings, which live on https://github.com/napari/napari

mission, values, and roadmap

For more information about our plans for napari you can read our mission and values statement, which includes more details on our vision for supporting a plugin ecosystem around napari. You can see details of the project roadmap here.

contributing

Contributions are encouraged! If you're new or unsure about anything check out our issues tracker or reach out on zulip before jumping in. It's nice to be able preview how your contribution will look on the web, so here we provide a brief summary of what's required for a local setup that will allow you to do so. Alternatively, our CI setup provides a preview link that shows your changes. Please read our contributing guide for more comprehensive information about contributing documentation.

quickstart: local setup

Option 1: Manual setup

• Check the prerequisites
  1. Create a clean Python (>=3.10) environment (e.g., with conda).
  2. In that environment, create an editable napari installation with the docs dependency group and a Qt backend. For example, after first forking and cloning the main napari project if you've not previously done so, run python -m pip install -e ".[pyqt]" --group docs from your napari/napari clone directory. This will use the default Qt backend.
  3. Fork this repository, napari/docs, and then clone your fork to your local machine. NB: you may want to name your fork e.g. napari-docs rather than just docs.
• Build locally

  • If you're building on Windows, a few extra steps are required; you can follow this guide.

  • From the root of your local clone of this repository, run one of these:

    • make html, for a full build, including the example gallery
    • make html-noplot, for a full build without building the example gallery
    • make slimfast, for a fast, parallel build of only sources in the docs repository, with no notebook cell outputs and no example gallery.

    Note: -live variants of these are available to auto-build when edited files are saved, e.g. slimfast-live. For more options, see the documentation.

• Preview locally, either dragging-and-dropping docs/_build/index.html into a browser, or deploying a local server with python3 -m http.server --directory docs/_build.

These steps should set you up to build and preview your docs contributions on your local machine. For more detailed instructions and tips, please visit the relevant sections of our contribution guide.

Option 2: Using pixi

Pixi provides a simple, cross-platform way to quickly build the documentation without manually installing dependencies or cloning the napari source repository.

Note: This option will clone the main napari repo from the main branch on GitHub into the pixi environment. For docstring changes in your local napari clone, use Option 1.

1. Install pixi (if not already installed):

   # Windows (PowerShell)
   iwr -useb https://pixi.sh/install.ps1 | iex
   
   # macOS/Linux
   curl -fsSL https://pixi.sh/install.sh | bash

   Important: After installation, you need to add pixi to your PATH:

   • Windows: Restart your PowerShell terminal, or run:

     $env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")

   • macOS/Linux: Restart your terminal, or run:

     # For bash
     source ~/.bashrc
     
     # For zsh (macOS default since version 10.15 Catalina)
     source ~/.zshrc
     
     # For fish shell
     fish_add_path ~/.pixi/bin

2. Verify pixi is properly installed

   pixi --version

3. Clone this repository:

   git clone https://github.com/napari/docs.git napari-docs
   cd napari-docs

4. Install dependencies (automatically detects your platform):

   pixi install

5. Build the docs using one of these commands:

   # Fast, parallel build (recommended for development)
   pixi run slimfast
   
   # Full build with example gallery
   pixi run html
   
   # Full build without gallery
   pixi run html-noplot
   
   # Auto-rebuild on file changes
   pixi run slimfast-live

   For more build options, see pixi task list.

6. Preview: Open docs/_build/html/index.html in your browser, or run:

   python3 -m http.server --directory docs/_build/html

Notes:

• pixi requires make to be installed on your computer.
• The pixi.toml is multi-platform for Windows, Linux, MacOS (both Intel and Apple Silicon).
• All build targets have cross-platform support in the Makefile.
• To clean build artifacts, run: pixi run clean
• If you update pixi, run pixi install again to refresh the environment.

code of conduct

napari has a Code of Conduct that should be honored by everyone who participates in the napari community.

governance

You can learn more about how the napari project is organized and managed from our governance model, which includes information about, and ways to contact the @napari/steering-council and @napari/core-devs.

citing napari

If you find napari useful please cite this repository using its DOI as follows:

napari contributors (2019). napari: a multi-dimensional image viewer for python. doi:10.5281/zenodo.3555620

Note this DOI will resolve to all versions of napari. To cite a specific version please find the DOI of that version on our zenodo page. The DOI of the latest version is in the badge at the top of this page.

help

We're a community partner on the image.sc forum and all help and support requests should be posted on the forum with the tag napari. We look forward to interacting with you there.

Bug reports should be made on our github issues using the bug report template. If you think something isn't working, don't hesitate to reach out - it is probably us and not you!

institutional and funding partners