npe2 docs #3769
npe2 docs #3769
Conversation
|
@tlambert03 @DragaDoncila @Carreau I'd love feedback! |
Codecov Report
@@ Coverage Diff @@
## main #3769 +/- ##
==========================================
- Coverage 83.05% 82.95% -0.11%
==========================================
Files 563 576 +13
Lines 46524 47451 +927
==========================================
+ Hits 38642 39362 +720
- Misses 7882 8089 +207
Continue to review full report at Codecov.
|
|
|
||
| ```bash | ||
| pip install -e . | ||
| napari |
There was a problem hiding this comment.
Can we update this to be a single command that "executes" the plugin? e.g. napari path/to/file.npy? That's not a super interesting example, but I always have to look up the equivalent command for pre-loading a plugin widget.
There was a problem hiding this comment.
Agreed it would be nice to bring that convenience from npe1 over. We're still thinking about how to accomplish it
docs/plugins/index.md
Outdated
|
|
||
| ## How to build plugins? | ||
|
|
||
| For a guide on how to create a plugin, see |
There was a problem hiding this comment.
before this page gets published, i think it should be super clear, on every "how to page" whether it's referring to npe1 or npe2. i don't see us referring to "hook specifications" quite as much with npe2, but rather "contributions"... so this index page, guiding people into what they might want to look at next, needs to be super clear about that.
There was a problem hiding this comment.
This is a good point. On the index page, I'm not quite sure how to deal with the npe1 to npe2 transition. I'll add text here making it clear this references npe1 and I'll add some text re npe2. I'll also be adding admonitions to the tops of the other plugin pages noting that npe2 exists and the current page deals with X plugin engine.
"hook specifications" ... "contributions"
I'm definitely trying to follow this convention throughout. "contributions" for npe2 and "hook specs" or "hook impls" for npe1.
docs/plugins/npe2_getting_started.md
Outdated
| `my_npy_reader`. This is the name that will be used for the python package. It | ||
| should conform to the [PEP8][] naming convention. | ||
|
|
||
| When the cookiecutter asked to include a reader plugin, we selected "y", and |
There was a problem hiding this comment.
(When the cookiecutter asked to include a reader plugin, could be removed with line numbers)
|
|
||
| ```bash | ||
| pip install -e . | ||
| napari |
There was a problem hiding this comment.
Agreed it would be nice to bring that convenience from npe1 over. We're still thinking about how to accomplish it
Co-authored-by: Talley Lambert <talley.lambert@gmail.com>
Co-authored-by: Talley Lambert <talley.lambert@gmail.com>
Co-authored-by: Talley Lambert <talley.lambert@gmail.com>
* introduce event debugging * update sample * one more comment * exclude .env_sample from check-manifest * allow toggle * more docs
|
|
||
| (commands)= | ||
|
|
||
| ## Commands |
There was a problem hiding this comment.
I'd really like to see almost all of this file be pulled from the Field(description=...) and the class docstrings of the npe2 manifest. Otherwise, we'll always have an issue with knowing whether they're in sync. If you want some tips for that, let me know
|
|
||
| (top-level-props)= | ||
|
|
||
| ## Top-level properties |
There was a problem hiding this comment.
I think Contributions should have its own page, rather than each individual subsection of contributions appearing as a flat header next to "top level props"
There was a problem hiding this comment.
I think this page is extremely easy to navigate: https://code.visualstudio.com/api/references/contribution-points
| might just ignore the `point` layers. The writer must return `None` for | ||
| unwritten layers. | ||
|
|
||
| ### Calling convention |
There was a problem hiding this comment.
we use the term function signature most other places. any reason not to keep that here?
There was a problem hiding this comment.
I use "calling convention" to refer to both the function signature and the requirements around when it's called.
For example, single and multi layer writers have different function signatures. Their behavior relative to one another is described by a calling convention.
Another example is the "autogenerate" flag modifying function widgets. The calling convention describes that, in the context where the function is invoked, it will be wrapped to produce a widget.
| @@ -0,0 +1,606 @@ | |||
| (npe2-manifest-spec)= | |||
There was a problem hiding this comment.
general thought on this file. I feel like it reads somewhere in between "tutorial" and "reference" ... making it a bit less useful for both purposes. If someone's made a plugin before and just can't remember what the manifest specification is, there should be a page where they can go to essentially see the schema, with bullet points for the fields, and probably one example. We also certainly need all of the more tutorial-like content here, but having them all together makes it a bit more cumbersome to reference?
There was a problem hiding this comment.
I agree - I like the idea of separating tutorial/concepts/reference. I also want to add guides for the specific plugin types.
I don't want to have to address that in this PR though. It'll be too complicated. I'd like to get this in as a good starting place, then work out a set of issues so we can get the structure where we want it piece by piece.
| `npe2` as soon as possible. See the [](npe2-migration-guide). | ||
| ``` | ||
|
|
||
| The **plugin manifest** is a specially formatted text file declaring the |
There was a problem hiding this comment.
we've already said this elsewhere (in the entry page). I'd love to see our documentation be leaner, which means we don't really need someone to be able to enter anywhere and bring them back up to speed. Let the top pages give the background, the inner pages be the reference, and the tutorial pages read like hand-holding how-to
There was a problem hiding this comment.
I think I might have removed this from the plugin index page. I have it here because this is where I define all these terms.
| defining the fields and their data types. These fields and their meanings are | ||
| described below. | ||
|
|
||
| A **plugin engine** is used to discover plugins, provide utilities for |
There was a problem hiding this comment.
they don't need to know this when writing the manifest
There was a problem hiding this comment.
I do refer to the "plugin engine" later on. But I don't refer to discovery. Should I remove the paragraph? It looks like a pretty reasonable idea. I could move the definition of plugin engine down to where it's used.
|
|
||
| (compatibility)= | ||
|
|
||
| ### Compatibility |
There was a problem hiding this comment.
there's a lot of background here, which is perhaps of interest to napari developers looking to modify the schema, but a lot for someone just writing a plugin who more or less just needs to know which number to use.
There was a problem hiding this comment.
I agree this is much too long. Can you suggest how you'd like to shrink it down?
I kind of like keeping just the first paragraph. Probably with a different section title.
|
closing in favor of #3818. This pr has gotten hard to review so I cleaned it up and made a new pr. |
NOTE
This PR has had a lot of comments and I've dirtied it up a bit. I'm going to clean it up and open a new PR for final review.
Description
This adds documentation for npe2 to the napari docs. Some of the details are awaiting the last few changes to the npe2 manifest before release.
I'll keep this as draft until npe2 release. Please feel free to review while this is in draft.
There is a
Type of change
Todo