Cookiecutter template for authoring (npe2-based) napari plugins.
NOTE: This repo is not meant to be cloned/forked directly! Please read "Getting Started" below
Install Cookiecutter and generate a new napari plugin project:
pip install cookiecutter
cookiecutter https://github.com/napari/cookiecutter-napari-plugin
Cookiecutter prompts you for information regarding your plugin (A new folder will be created in your current working directory):
full_name [Napari Developer]: Ramon y Cajal
email [yourname@example.com]: ramon@cajal.es
github_username_or_organization [githubuser]: neuronz52
# NOTE: for packages whose primary purpose is to be a napari plugin, we
# recommend using the 'napari-' prefix in the package name.
# If your package provides functionality outside of napari, you may
# choose to leave napari out of the name.
plugin_name [napari-foobar]: napari-growth-cone-finder
Select github_repository_url:
1 - https://github.com/neuronz52/napari-growth-cone-finder
2 - provide later
Choose from 1, 2 [1]:
module_name [growth_cone_finder]: napari_growth_cone_finder
display_name [napari FooBar]: Growth Cone Finder
short_description [A simple plugin to use with napari]:
# you can select from various plugin template examples
include_reader_plugin [y]:
include_writer_plugin [y]:
include_sample_data_plugin [y]:
include_dock_widget_plugin [y]:
use_git_tags_for_versioning [n]:
Select license:
1 - BSD-3
2 - MIT
3 - Mozilla Public License 2.0
4 - Apache Software License 2.0
5 - GNU LGPL v3.0
6 - GNU GPL v3.0
Choose from 1, 2, 3, 4, 5, 6 (1, 2, 3, 4, 5, 6) [1]:
You just created a minimal napari plugin, complete with tests and ready for automatic deployment!
For more detailed information on each prompt see the prompts reference.
napari-growth-cone-finder/
│
├── .github
│ └── workflows
│ └── test_and_deploy.yml
├── LICENSE
├── MANIFEST.in
├── napari_growth_cone_finder
│ ├── __init__.py
│ ├── _widget.py
│ ├── _reader.py
│ ├── napari.yaml
│ └── _tests
│ ├── __init__.py
│ ├── test_widget.py
│ └── test_reader.py
├── pyproject.toml
├── README.md
├── setup.cfg
└── tox.ini
NOTE: This is important not only for version management, but also if you want to
pip install your package locally for testing with pip install -e .
. (because
the version of your package is managed using git tags,
see below)
cd napari-growth-cone-finder
git init
git add .
git commit -m 'initial commit'
Create a new github repository
Add your newly created github repo as a remote and push:
# here, continuing with the example above...
# but replace with your own username and repo name
git remote add origin https://github.com/neuronz52/napari-growth-cone-finder.git
git push -u origin main
The repository should already be setup to run your tests each time you push an
update (configuration is in .github/workflows/test_and_deploy.yml
). You can
monitor them in the "Actions" tab of your github repository. If you're
following along, go have a look... they should be running right now!
Currently, the timeout for these runs is set to 30 minutes to save resources. You can modify the settings if necessary. Here you can find information on GitHub workflows and the timeout parameter.
When the tests are done, test coverage will be viewable at
codecov.io (assuming your repository is public):
https://codecov.io/gh/<your-github-username>/<your-package-name>
You will need to enable the codecov github app for this to work. See here to install the codecov github app and give it access to your napari plugin repository.
Your new package is also nearly ready to automatically deploy to PyPI
(whenever you create a tagged release), so that your users can simply pip install
your package. You just need to create an API token to authenticate
with PyPi, and then add it to your github
repository:
You are now setup for automatic deployment!
Each time you want to deploy a new version, you just need to create a tagged commit, and push it to your main branch on github. Your package is set up to use setuptools_scm for version management, meaning you don't need to hard-code your version anywhere in your package. It will be inferred from the tag each time you release.
# the tag will be used as the version string for your package
# make it meaningful: https://semver.org/
git tag -a v0.1.0 -m "v0.1.0"
# make sure to use follow-tags so that the tag also gets pushed to github
git push --follow-tags
Note: as of git 2.4.1, you can set
follow-tags
as default withgit config --global push.followTags true
Monitor the "actions" tab on your github repo for progress... and when the "deploy" step is finished, your new version should be visible on pypi:
https://pypi.org/project/<your-package-name>/
and available for pip install with:
# for example
pip install napari-growth-cone-finder
Tests are automatically setup to run on github when you push to your repository.
You can run your tests locally with pytest.
You'll need to make sure that your package is installed in your environment,
along with testing requirements (specified in the setup.cfg extras_require
section):
pip install -e ".[testing]"
pytest
Documentation generation is not included in this template. We recommend following the getting started guides for one of the following documentation generation tools:
This template includes a default yaml configuration for pre-commit.
Among other things, it includes checks for best practices in napari plugins.
You may edit the config at .pre-commit-config.yaml
To use it run:
pip install pre-commit
pre-commit install
You can also have these checks run automatically for you when you push to github by installing pre-commit ci on your repository.
This template also includes a default yaml configuration for Dependabot. This can help you check for security updates to easily update vulnerable dependencies.
You will still need to enable Dependabot in your github settings, see the instructions at this link. Your Dependabot configuration file is located at .github/dependabot.yml
.
README.md
file that contains useful information about your pluginPlease consult the napari plugin docs for more information on how to create a plugin.
Details on why this plugin template is using the src
layout can be found here and here
If you encounter any problems with this cookiecutter template, please [file an issue] along with a detailed description.
Distributed under the terms of the BSD-3 license, cookiecutter-napari-plugin
is free and open source software.