Minimal Cookiecutter template for authoring napari plugins.
This template requires Cookiecutter 1.4.0 "Shortbread" or higher
- Installable PyPI package featuring a
setup.py
- tox test suite, testing various python versions and platforms.
README.md
file that contains useful information about your plugin- Continuous integration configuration for github actions that handles testing and deployment of tagged releases
- git-tag-based version management with setuptools_scm
- Optional documentation with either Sphinx or MkDocs
- Choose from several licenses, including BSD-3, MIT, MPL v2.0, Apache v2.0, GNU GPL v3.0, or GNU LGPL v3.0
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 [[email protected]]: [email protected]
github_username [githubuser]: neuronz52
# NOTE: don't preface your plugin name with "napari"!
# It will be prepended automatically
plugin_name [foobar]: growth-cone-finder
module_name [growth_cone_finder]: growth_cone_finder
short_description [A simple plugin to use with napari]:
Select docs_tool:
1 - mkdocs
2 - sphinx
3 - none
Choose from 1, 2, 3 [1]: 3
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]:
INFO:post_gen_project:Moving files for mkdocs.
You just created a minimal napari plugin, complete with tests and ready for automatic deployment!
napari-growth-cone-finder/
│
├── .github
│ └── workflows
│ └── test_and_deploy.yml
├── docs
│ └── index.md
├── LICENSE
├── MANIFEST.in
├── mkdocs.yml
├── napari_growth_cone_finder
│ ├── __init__.py
│ ├── _tests
│ │ ├── __init__.py
│ │ └── test_grown_cone_finder.py
│ └── growth_cone_finder.py
├── README.md
├── requirements.txt
├── setup.py
└── 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 master
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!
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>
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:
- If you don't already have one, create an account at PyPI
- Verify your email address with PyPI, (if you haven't already)
- Generate an API token at PyPi: In your account settings go to the API tokens section and select "Add API token". Make sure to copy it somewhere safe!
- Create a new encrypted secret" in your github repository with the name "TWINE_API_KEY", and paste in your API token.
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 master 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
You can run your tests locally in multiple different python environments using
tox, just by entering tox
on the command line. If you are using conda
for
environment management, you may wish to install tox-conda
to make tox play
nice with conda.
pip install tox tox-conda
tox -e py36,py37,py38 # run tests on multiple python versions
If you don't wish to test locally on all supported python versions, you can test
quicker by just using pytest directly, (but you'll need to make sure that
pytest
and your package is installed in your environment):
pip install -e .
pip install pytest
pytest # run test in current environment
If you chose to create docs with your plugin read the corresponding docs for Sphinx or MkDocs
Please consult the napari plugin docs for more information on how to create a plugin.
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.