diff --git a/README.md b/README.md index b08254e..0cbd9ec 100644 --- a/README.md +++ b/README.md @@ -1,283 +1,5 @@ -# cookiecutter-napari-plugin +# ⚠️ **OUTDATED DO NOT USE** ⚠️ -[Cookiecutter] template for authoring ([npe2]-based) [napari] plugins. +## cookiecutter-napari-plugin -**NOTE: This repo is not meant to be cloned/forked directly! Please read "Getting Started" below** - -## Getting Started - -### Create your plugin package - -Install [Cookiecutter] and generate a new napari plugin project: - -```bash -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): - -```bash -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](./PROMPTS.md). - -```no-highlight -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 -``` - -### Initialize a git repository in your package - -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](#automatic-deployment-and-version-management)) - -```bash -cd napari-growth-cone-finder -git init -git add . -git commit -m 'initial commit' -``` - -### Upload it to github - -1. Create a [new github repository] - -2. Add your newly created github repo as a remote and push: - - ```bash - # 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 - ``` - -### Monitor testing and coverage - -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](https://docs.github.com/en/actions/learn-github-actions) and the [timeout parameter](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idtimeout-minutes). - -When the tests are done, test coverage will be viewable at -[codecov.io](https://codecov.io/) (assuming your repository is public): -`https://codecov.io/gh//` - -You will need to enable the [codecov](https://github.com/apps/codecov) github app -for this to work. See [here](https://github.com/apps/codecov/installations/new) -to install the codecov github app and give it access to your napari plugin repository. - -### Set up automatic deployments - -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](https://pypi.org/help/#apitoken), and then add it to your github -repository: - -1. If you don't already have one, [create an - account](https://pypi.org/account/register/) at [PyPI] -2. Verify your email address with PyPI, (if you haven't already) -3. Generate an [API token](https://pypi.org/help/#apitoken) at PyPi: In your - [account settings](https://pypi.org/manage/account/) go to the API tokens - section and select "Add API token". Make sure to copy it somewhere safe! -4. [Create a new encrypted - secret](https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets#creating-encrypted-secrets)" - in your github repository with the name "TWINE_API_KEY", and paste in your - API token. - -You are now setup for automatic deployment! - -### Automatic deployment and version management - -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](https://github.com/pypa/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. - -```bash -# 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 with -> `git 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//` - -and available for pip install with: - -```bash -# for example -pip install napari-growth-cone-finder -``` - -### Running tests locally - -Tests are automatically setup to run on github when you push to your repository. - -You can run your tests locally with [pytest](https://docs.pytest.org/en/7.1.x/). -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): - -```bash -pip install -e ".[testing]" -pytest -``` - -### Create your documentation - -Documentation generation is not included in this template. -We recommend following the getting started guides for one of the following -documentation generation tools: - -1. [Sphinx] -2. [MkDocs] -3. [JupyterBook] - -### Pre-commit - -This template includes a default yaml configuration for [pre-commit](https://pre-commit.com/). -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: - -```bash -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](https://pre-commit.ci/) on your repository. - -## Dependabot - -This template also includes a default yaml configuration for [Dependabot](https://docs.github.com/en/code-security/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](https://docs.github.com/en/code-security/dependabot/dependabot-security-updates/configuring-dependabot-security-updates#managing-dependabot-security-updates-for-your-repositories). Your Dependabot configuration file is located at `.github/dependabot.yml`. - -## Features - -- Installable [PyPI] package -- [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] -- Choose from several licenses, including [BSD-3], [MIT], [MPL v2.0], [Apache - v2.0], [GNU GPL v3.0], or [GNU LGPL v3.0] - -## Resources - -Please consult the [napari plugin -docs](https://napari.org/stable/plugins/index.html) for more information on -how to create a plugin. - -Details on why this plugin template is using the `src` layout can be found [here](https://blog.ionelmc.ro/2014/05/25/python-packaging/#the-structure) and [here](https://hynek.me/articles/testing-packaging/) - -## Issues - -If you encounter any problems with this cookiecutter template, please [file an -issue] along with a detailed description. - -## License - -Distributed under the terms of the [BSD-3] license, `cookiecutter-napari-plugin` -is free and open source software. - -[napari organization]: https://github.com/napari/ -[gitter_badge]: https://badges.gitter.im/Join%20Chat.svg -[gitter]: https://gitter.im/napari/cookiecutter-napari-plugin?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge "Join Chat on Gitter.im" -[travis_badge]: https://travis-ci.org/napari/cookiecutter-napari-plugin.svg?branch=main -[travis]: https://travis-ci.org/napari/cookiecutter-napari-plugin "See Build Status on Travis CI" -[docs_badge]: https://readthedocs.org/projects/cookiecutter-napari-plugin/badge/?version=latest -[documentation]: https://cookiecutter-napari-plugin.readthedocs.io/en/latest/ "Documentation" -[cookiecutter]: https://github.com/audreyr/cookiecutter -[napari]: https://github.com/napari/napari -[npe2]: https://github.com/napari/npe2 -[pypi]: https://pypi.org/ -[tox]: https://tox.readthedocs.io/en/latest/ -[file an issue]: https://github.com/napari/cookiecutter-napari-plugin/issues -[sphinx]: https://www.sphinx-doc.org/en/master/usage/quickstart.html -[mkdocs]: https://www.mkdocs.org/getting-started/ -[jupyterbook]: https://jupyterbook.org/en/stable/start/your-first-book.html -[mit]: http://opensource.org/licenses/MIT -[mpl v2.0]: https://www.mozilla.org/media/MPL/2.0/index.txt -[bsd-3]: http://opensource.org/licenses/BSD-3-Clause -[gnu gpl v3.0]: http://www.gnu.org/licenses/gpl-3.0.txt -[gnu lgpl v3.0]: http://www.gnu.org/licenses/lgpl-3.0.txt -[apache v2.0]: http://www.apache.org/licenses/LICENSE-2.0 -[travis ci]: https://travis-ci.com/ -[appveyor]: http://www.appveyor.com/ -[pypa code of conduct]: https://www.pypa.io/en/latest/code-of-conduct/ -[shortbread]: https://github.com/audreyr/cookiecutter/releases/tag/1.4.0 -[osi_certified]: https://opensource.org/trademarks/osi-certified/web/osi-certified-120x100.png -[osi]: https://opensource.org/ -[github actions]: https://github.com/features/actions -[new github repository]: https://help.github.com/en/github/getting-started-with-github/create-a-repo -[setuptools_scm]: https://github.com/pypa/setuptools_scm +This repository is archived and no longer maintained. Please see [napari/napari-plugin-template](https://github.com/napari/napari-plugin-template/?tab=readme-ov-file#napari-plugin-template) for an up-to-date template from which to start a napari plugin.