📚 New content request

The guide to making "Your first plugin" has a really useful section entitled "What is a plugin?". In the Plugin docs restructure issue a new page was suggested, called "Plugin anatomy" that would go into more detail on this topic. The idea of this page is to give an overview of the minimal elements that make a napari plugin, and link out to the related documents. I think this would be best suited as an explanation style page in the Diátaxis framework. I'm curious what you think on the idea, and what people would like to see in such a page if it was created.

Document outline

To get the ball rolling, perhaps the new page could be something like this:

Plugin anatomy (or what is a plugin?)

Napari plugins are just Python packages. Minimally, they must:

Include a static plugin manifest file that details the contributions contained in the plugin.
Declare a napari.manifest entry point that allows napari to detect the plugin at runtime.

Static plugin manifest

The static plugin manifest is a YAML or TOML file that contains metadata about your plugin and a set of plugin contributions, which define what functionality your plugin adds. This file enables napari to know what your plugin provides without having to import it, and is used to populate the napari viewer. By convention, this file is called napari.yaml and it is placed in the top level module of your package. Make sure to include this file in your package data so that it gets included in your package. Check out the full manifest specification here.

Plugin contributions

A significant part of the plugin manifest file is the contributions section. Contributions are the individual pieces of functionality that your plugin provides, for example, to provide support for reading a new file format in napari, you would add a reader contribution with associated file extensions. This enables napari to use your plugin to support reading from a file with those extensions, e.g., if a user drag and drops such a file into the viewer. Check out the full contribution specification here and follow our guide to learn how to use them.

Manifest entry point

The manifest entry point is a string that informs napari where to find your static plugin manifest file. You can instruct napari where to find your manifest file by adding a napari.manifest entry point to your package metadata. For example, in your setup.cfg file:

# tell napari where to find to your manifest
[options.entry_points]
napari.manifest =
    example-plugin = example_plugin:napari.yaml

# make sure it gets included in your package
[options.package_data]
example-plugin = napari.yaml

Discovery by the napari plugin manager

The napari plugin manager and the napari hub will automatically pick up any Python packages distributed on the Python Package Index (PyPI), and annotated with the tag Framework :: napari. To hide your plugin from the napari plugin manager, you can set visibility to 'hidden' in your manifest (see the manifest reference). Check out the napari hub guide to visibility to remove your plugin from the napari hub. Alternatively, to remove your plugin from both the napari hub the napari plugin manager, you can remove the Framework :: napari from your package metadata.

In the bundled version of napari, downloaded from napari/releases, the only plugins that are supported are those that are published on conda-forge. So it can be a good idea to upload your plugin to both PyPI and conda-forge to support both sets of users if possible.

The plugin manager information that is displayed to a napari user is populated from a mixture of standard metadata (such as the package name and description, that would also be parsed by PyPI, for example) and napari specific information from the static plugin manifest.

Getting started

The easiest way to create all of this plugin structure following the best practices is to use the napari plugin template. This will also provide some additional convenience to support developing your plugin, such as helpful GitHub actions to automatically deploy your plugin to PyPI on release.

The previous plugin system

If you are browsing through plugins, you may come across some plugins that don't have a manifest file. These were likely created in the older npe1 system. You can check out the npe1 guide if want to understand the old system better, and see the npe2 conversion guide if you have an npe1 plugin which you want to convert to npe2.

napari / docs

Plugin anatomy, or what is a plugin? #225