Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update finding and installing plugin docs #541

Open
wants to merge 7 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file modified docs/_static/images/plugin-install-dialog.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/_static/images/plugin-manager.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
50 changes: 31 additions & 19 deletions docs/plugins/start_using_plugins/finding_and_installing_plugins.md
Copy link
Contributor

@TimMonko TimMonko Dec 19, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is great. What comes to mind as missing is mention of how to upgrade plugins. I think, by default, a user working through npm has to uninstall and then reinstall the version they want. Is that correct? Is this the recommended way for most users?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the new plugin manager should update plugins too.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Automagically? I remember there used to be an 'upgrade' button or something, but on main that doesn't seems to be the case -- just uninstall is available (the plugin here has v0.9.7 available through npm, I intentionally used npm to download v0.9.5):
image

napari: 0.5.6.dev10+g224f8e9c
Platform: Windows-11-10.0.22631-SP0
Python: 3.12.8 | packaged by conda-forge | (main, Dec 5 2024, 14:06:27) [MSC v.1942 64 bit (AMD64)]
Qt: 5.15.2
PyQt5: 5.15.11
NumPy: 1.26.4
SciPy: 1.14.1
Dask: 2024.12.1
VisPy: 0.14.3
magicgui: 0.10.0
superqt: 0.7.0
in-n-out: 0.2.1
app-model: 0.3.1
psygnal: 0.11.1
npe2: 0.7.7
pydantic: 2.10.4

OpenGL:
- GL version: 4.6.0 NVIDIA 551.78
- MAX_TEXTURE_SIZE: 32768
- GL_MAX_3D_TEXTURE_SIZE: 16384

Screens:
- screen 1: resolution 1920x1080, scale 2.0
- screen 2: resolution 1440x2560, scale 1.0

Optional:
- numba: 0.60.0
- triangle: 20230923
- napari-plugin-manager: 0.1.3

Settings path:
- C:\Users\timmo\AppData\Local\napari\napari-testing_e9e6cb9e948feb28aa4661b58255680aebaae620\settings.yaml

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Um it should work?
https://napari.org/napari-plugin-manager/index.html#updating-a-plugin
Maybe there's been a regression somewhere or it's another conda vs pip difference?

Original file line number Diff line number Diff line change
Expand Up @@ -2,42 +2,54 @@
# 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 this data, together with additional
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

'This data' is ambiguous. I'm not sure how necessary it is. Maybe just something like' The napari-hub uses plugin-provided metadata to produce a more user-friendly way to find napari plugins.

metadata, to produce a more 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.
Comment on lines 13 to 14
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Similarly, the napari application lists plugins, annotated on PyPI with `Framework :: napari`,
in the `Plugins > Install/Uninstall Plugins` menu.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Redundant with below section, but especially with testing_and_publish/deploy.md


## 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, using the [napari plugin manager](https://napari.org/napari-plugin-manager/).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps it should be stated that npm is only installed with pip install napari[all], conda install napari, and the bundled app?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh this is a good point! The plugin manager has been devolved, so it's not in napari/napari anymore.

To install a new plugin, click the "Plugins" menu and select "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 'pip' by name/url, or drop file..."
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I assume this is meant to say 'conda' or something for one of them? Right now both say 'pip'. (my npm is currently not connecting in any install, no idea why, so I can't check)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

oops yes, wrong copy/paste!

(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 with to install, clicking on "Installation Info"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
3. Advanced installation: after you have searched for the plugin you with to install, clicking on "Installation Info"
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/.
1 change: 0 additions & 1 deletion docs/plugins/start_using_plugins/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
19 changes: 9 additions & 10 deletions docs/plugins/testing_and_publishing/deploy.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
19 changes: 5 additions & 14 deletions docs/plugins/virtual_environment_docs/2-deploying-your-plugin.md
Original file line number Diff line number Diff line change
Expand Up @@ -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. 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.
Expand Down Expand Up @@ -92,8 +83,8 @@ 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).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Note that in order to deploy to `conda-forge` *all* build and run requirements (i.e. dependencies) *must* be available on `conda-forge`.

1. Fork https://github.com/conda-forge/staged-recipes
Expand All @@ -102,7 +93,7 @@ This is only a brief guide to deploying to `conda-forge`. More information can b
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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
This is **far** easier if you already have an `sdist` published to PyPI.
This is **far** easier if you already have an `sdist` published to PyPI.
Updating your package on conda-forge: 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 you must address any changes and approve the pull request.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Style this better than I have, but I think this is really important to add


Expand Down
Loading