diff --git a/docs/_static/images/plugin-install-dialog.png b/docs/_static/images/plugin-install-dialog.png index 881d92eb..793c933b 100644 Binary files a/docs/_static/images/plugin-install-dialog.png and b/docs/_static/images/plugin-install-dialog.png differ diff --git a/docs/_static/images/plugin-manager.png b/docs/_static/images/plugin-manager.png new file mode 100644 index 00000000..97251f2c Binary files /dev/null and b/docs/_static/images/plugin-manager.png differ diff --git a/docs/plugins/start_using_plugins/finding_and_installing_plugins.md b/docs/plugins/start_using_plugins/finding_and_installing_plugins.md index add6904d..09a5226d 100644 --- a/docs/plugins/start_using_plugins/finding_and_installing_plugins.md +++ b/docs/plugins/start_using_plugins/finding_and_installing_plugins.md @@ -2,42 +2,52 @@ # Finding and installing plugins Information about available plugins can be found in the following places: -- napari plugins are Python packages distributed on the Python Package Index +- **PyPI:** napari plugins are Python packages distributed on the Python Package Index (PyPI), and annotated with the tag [`Framework :: napari`](https://pypi.org/search/?q=&o=&c=Framework+%3A%3A+napari) -- The conda-forge may be searched for napari plugins from - their [package search page](https://conda-forge.org/packages/). -- The [napari hub](https://napari-hub.org) uses this data, together with additional - metadata, to produce a more user friendly way to find napari plugins. +- **conda-forge:** You can search for napari plugins from + the conda-forge [package search page](https://conda-forge.org/packages/). +- **napari hub:** The [napari hub](https://napari-hub.org) uses package data, together with additional + metadata, to produce a user-friendly way to find napari plugins. -Similarly, the napari application lists plugins, annotated on PyPI with `Framework :: napari`, -in the `Plugins > Install/Uninstall Plugins` menu. ## Installing plugins with napari All PyPI packages annotated with the `Framework :: napari` tag can be installed -directly from within napari: -Firstly, from the “Plugins” menu, select “Install/Uninstall Plugins...”. +directly from within napari, when the user has installed the [napari plugin manager](https://napari.org/napari-plugin-manager/). +After the napari plugin manager is available, install a plugin by clicking the "Plugins" menu and selecting "Install/Uninstall Plugins...". Then, in the plugin installer menu that opens, you can either: ![napari viewer's Plugins menu with Install/Uninstall Plugins as the first item.](../../_static/images/plugin-menu.png) -1. Install plugins from the list: you can scroll through the list of “Available Plugins”, or - filter plugins using the text box at the top of the dialog. From the list, - you can then install a plugin by clicking the `install` button in the - tile of the plugin you want to install. You can also uninstall or update - plugins from this dialog in a similar way under the “Installed Plugins” section. +1. Install plugins by searching: you can start typing in the text box at the top of the dialog to filter plugins. From + the resulting list, you can then install a plugin by clicking the `Install` button in the tile of the plugin you want + to install. You can also uninstall or update plugins from this dialog in a similar way under the "Installed Plugins" + section. -2. Install plugins via manual input: where it says “Install by name/URL”, - enter the name of the plugin you want to install (or *any* valid pip - [requirement - specifier](https://pip.pypa.io/en/stable/reference/requirement-specifiers/) - or [VCS scheme](https://pip.pypa.io/en/stable/topics/vcs-support)). Then click - the “Install” button next to the input bar. This method allows for more flexibility - in the plugins you can install, but it is also a bit more advanced. +2. Install plugins via manual input: at the bottom of the napari plugin manager window, there is a text box that will + say either "install with 'pip' by name/url, or drop file...", or "install with 'conda' by name/url, or drop file..." + (depending on how you installed napari). Enter the name of the plugin you want to install (or *any* valid pip or conda + [requirement specifier](https://pip.pypa.io/en/stable/reference/requirement-specifiers/) or + [VCS scheme](https://pip.pypa.io/en/stable/topics/vcs-support)). Then, click the "Install" button next to the input + bar. This method allows for more flexibility in the plugins you can install, but it is also a bit more advanced. ![napari viewer's Plugin dialog. At the bottom of the dialog, there is a place to install by name, URL, or dropping in a file.](../../_static/images/plugin-install-dialog.png) + ```{admonition} Example + To install `napari-svg`, enter `napari-svg` in the text field and press {kbd}`Enter` or click "Install". This is equivalent to running `pip install napari-svg`. + ``` ```{admonition} Example If you want to install `napari-svg` directly from the development branch on the [github repository](https://github.com/napari/napari-svg), enter `git+https://github.com/napari/napari-svg.git` in the text field. ``` + ```{admonition} Example + If you want to install `napari-svg` from a specific release, enter `napari-svg==0.1.0` in the text field. + ``` + +3. Advanced installation: after you have searched for the plugin you wish to install, clicking on "Installation Info" + button will open choices for installation source (conda or pip) and version selection. After choosing the desired + options, you can click the "Install" button to install the plugin. + + ![napari plugin manager with the Installation Info button expanded to show conda or pip as installation source.](../../_static/images/plugin-manager.png) + +For more comprehensive documentation on the napari-plugin-manager, see https://napari.org/napari-plugin-manager/. \ No newline at end of file diff --git a/docs/plugins/start_using_plugins/index.md b/docs/plugins/start_using_plugins/index.md index e280754e..8a637b28 100644 --- a/docs/plugins/start_using_plugins/index.md +++ b/docs/plugins/start_using_plugins/index.md @@ -26,4 +26,3 @@ Submit issues to the [napari github repository][napari_issues]. [napari_issues]: https://github.com/napari/napari/issues/new/choose [napari_zulip]: https://napari.zulipchat.com/ -[napari_hub]: https://napari-hub.org \ No newline at end of file diff --git a/docs/plugins/testing_and_publishing/deploy.md b/docs/plugins/testing_and_publishing/deploy.md index 42aed956..1ea9446c 100644 --- a/docs/plugins/testing_and_publishing/deploy.md +++ b/docs/plugins/testing_and_publishing/deploy.md @@ -40,16 +40,15 @@ in the builtin plugin installer dialog. If you used the {ref}`napari-plugin-template`, you can also [setup automated deployments][autodeploy] on GitHub for every tagged commit. -````{admonition} What about conda? -While you are free to distribute your plugin on anaconda cloud in addition to -or instead of PyPI, the built-in napari plugin installer doesn't currently install -from conda. In this case, you may guide your users to install your package on the -command line using conda in your readme or documentation. - -A future version of napari and the napari stand-alone application may support -directly installing from conda. As such, publishing to conda-forge can be a good -idea. Checkout [deploying to anaconda](deploying-to-anaconda) for more details. -```` +```{admonition} conda-forge +:class: attention + +You can also deploy your plugin to conda-forge. Check out [deploying to conda-forge](deploying-to-conda-forge) for more +details on how to do that. +``` + +The [napari-plugin-manager](https://napari.org/napari-plugin-manager/) can be used to install plugins deployed to both +PyPI and conda-forge. When you are ready for users, announce your plugin on the [Image.sc forum](https://forum.image.sc/tag/napari). diff --git a/docs/plugins/virtual_environment_docs/2-deploying-your-plugin.md b/docs/plugins/virtual_environment_docs/2-deploying-your-plugin.md index 1ae82f2f..360335ec 100644 --- a/docs/plugins/virtual_environment_docs/2-deploying-your-plugin.md +++ b/docs/plugins/virtual_environment_docs/2-deploying-your-plugin.md @@ -2,17 +2,8 @@ This guide explains some of the techniques you can use to deploy your plugin. -## This guide covers: - -- [Overview of PyPI and Anaconda](#overview-of-pypi-and-anaconda) -- [Building your package](#building-your-package) -- [Deploying plugins to PyPI](#deploying-plugins-to-pypi) - - [Manually via twine](#manually-via-twine) - - [Automatically via GitHub actions](#automatically-via-github-actions) -- [Deploying to Anaconda](#deploying-to-anaconda) - -## Overview of PyPI and Anaconda -PyPI and Anaconda are two options for how you distribute your package and allow your users to more easily find and install it. Try to deploy to both! But for now, try to at least use PyPI. You can always also provide your users with manual installation instructions (e.g. if you want them to use `conda` or have specific dependencies). +## Overview of PyPI and conda +PyPI and conda are two options for how you distribute your package and allow your users to more easily find and install it. Ideally, try to deploy to both. But for now, try to at least use PyPI. You can always also provide your users with manual installation instructions (e.g. if you want them to use `conda` or have specific dependencies). ### Building your package `sdist` means source distribution. An `sdist` includes all of the files that are required to *build* your package. An `sdist` may require specific additional software (e.g. compilers) to actually build. @@ -92,20 +83,26 @@ jobs: **Note:** Gate this action on some criterion, e.g. a git tag as above, or [some other criterion](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows). -(deploying-to-anaconda)= -## Deploying to Anaconda +(deploying-to-conda-forge)= +## Deploying to conda-forge This is only a brief guide to deploying to `conda-forge`. More information can be found in the [conda-forge docs](https://conda-forge.org/docs/maintainer/adding_pkgs.html). - +To deploy a plugin to `conda-forge`, the plugin's build and run requirements **must** be available on `conda-forge` so the plugin and its dependencies may be installed. 1. Fork https://github.com/conda-forge/staged-recipes 2. Create a new branch 3. Create a new folder in recipes directory (copy the existing example) 4. Update the **meta.yaml** file to include your package's build and run requirements 5. Commit and open a PR to https://github.com/conda-forge/staged-recipes -Once your recipe is approved and merged, the rest happens *automagically*, and your package will appear on the anaconda cloud. +Once your recipe is approved and merged, the rest happens *automagically*, and your package will appear on the [conda-forge package list](https://conda-forge.org/packages/). This is **far** easier if you already have an `sdist` published to PyPI. +```{admonition} Updating your package on conda-forge +:class: important + +By default, when a new release is detected on PyPI, conda-forge bots will automatically make a pull requests to your `conda-forge/package-name-feedstock`, and the plugin maintainer must review, make changes, if needed, and approve the pull request. +``` + ## Other topics in this series: * [Virtual environments](./1-virtual-environments.md) * [Version management](./3-version-management.md)