-
Notifications
You must be signed in to change notification settings - Fork 39
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
base: main
Are you sure you want to change the base?
Changes from all commits
5f07599
70520ee
f2e4f4d
3ccb513
df79cef
b4cf0d6
c15da4f
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change | ||||
---|---|---|---|---|---|---|
|
@@ -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 | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Redundant with below section, but especially with |
||||||
|
||||||
## 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/). | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Perhaps it should be stated that npm is only installed with There was a problem hiding this comment. Choose a reason for hiding this commentThe 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..." | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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) There was a problem hiding this comment. Choose a reason for hiding this commentThe 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" | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
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/. |
Original file line number | Diff line number | Diff line change | ||||||||
---|---|---|---|---|---|---|---|---|---|---|
|
@@ -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. | ||||||||||
|
@@ -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). | ||||||||||
|
||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||||||
1. Fork https://github.com/conda-forge/staged-recipes | ||||||||||
|
@@ -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. | ||||||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 |
||||||||||
|
||||||||||
|
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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](https://private-user-images.githubusercontent.com/47310455/397581007-61267920-12f3-4657-8868-d2e5e7f1a865.png?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MzkzNTA0MzgsIm5iZiI6MTczOTM1MDEzOCwicGF0aCI6Ii80NzMxMDQ1NS8zOTc1ODEwMDctNjEyNjc5MjAtMTJmMy00NjU3LTg4NjgtZDJlNWU3ZjFhODY1LnBuZz9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNTAyMTIlMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjUwMjEyVDA4NDg1OFomWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPTU3MmQyMmI4ZmYxNDlmMTk2NjVhMGI4NGEwNWE0ZDQ5MWM0YzUwNjgzNGJmMjE5ZmMyZWUyOTkwZTVhMzNmY2EmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0In0.QgGAny7DNgbpWLYCApv6Hn3_aeT_9i2gZnymslOMlnc)
There was a problem hiding this comment.
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?