From c1bf91b3378b80d3e6bfa75d5684baba1328cffd Mon Sep 17 00:00:00 2001 From: Draga Doncila Pop <17995243+DragaDoncila@users.noreply.github.com> Date: Sat, 22 Jun 2024 07:51:55 +0700 Subject: [PATCH] NAP-6: Updates after discussion and review (#312) # Description This PR updates NAP-6 after feedback on #77, discussion at the napari hackathon (notes [here](https://hackmd.io/fmKp0If5RkiwWIxYYRdKpg#Menu-contributions-notes) but also linked in doc), and discussions in community meetings in recent weeks. ## Still to be decided - [x] `npe2` allows users to define new submenus as well as menu items. **Should plugin developers be allowed to add new submenus to contributable menus?** Decision: yes, but not to the top level `Layers` menu, and the context menu shouldn't actually be contributable as it's already very long. - [x] It's not clear that the `Tracks` and `Classification` submenus are as well defined as the rest. Classification at least I'm not even sure how to describe. **Should we remove `Tracks` and `Classification` from the initial list of contributable menus?** Decision: No, we like both! --------- Co-authored-by: alisterburt Co-authored-by: Lucy Liu --- docs/naps/6-contributable-menus.md | 345 +++++++++++++++++++---------- 1 file changed, 229 insertions(+), 116 deletions(-) diff --git a/docs/naps/6-contributable-menus.md b/docs/naps/6-contributable-menus.md index 4f013f37..9459b92b 100644 --- a/docs/naps/6-contributable-menus.md +++ b/docs/naps/6-contributable-menus.md @@ -18,8 +18,8 @@ Since the initial release of `npe2` infrastructure has been in place for plugin developers to declare **menu contributions**. These contributions add new items to menus in napari that have been deemed **contributable**. -Until now, only the layer context menu (available through right clicking on -a layer in the layer list) has been contributable, but much discussion +The machinery for allowing plugins to contribute to menus has been largely +in place for a while, but much discussion has occurred on the list of menus we wish to open up for contribution and the guiding principles behind the organization of this list. @@ -116,16 +116,23 @@ This NAP proposes new menu IDs and new top level menus to open for contribution. ### What do Menu Contributions do? `MenuItem` contributions can be thought of as auxiliary contributions that -provide a dispatch mechanism for binding an existing contribution to a menu item and -executing it. Currently these would strictly be `widget` contributions as the other -contribution types (reader, writer, sample data) have defined menu locations. However, -this mechanism can easily be extended to other commands, which can take as input +allow you to place an existing contribution into one of napari's menus. + +Currently only `widget` contributions and pure commands could be placed in menus, as the other +contribution types (reader, writer, sample data) already have defined locations +and dispatch mechanisms. + +When `widget` contributions are placed in a menu, clicking on that menu item +will simply open the associated `widget`. However, pure commands can take as input `napari` objects like specific layers, or the `Viewer`, and produce -output the `Viewer` uses - currently this would be new layers. +output the `Viewer` uses - currently this would be new layers. For example, +you could have a command that creates a new layer with specific features, +or one that edits the rendering properties of an existing layer. Moving forward, new contribution types could be defined that allow plugin developers to run context aware commands that interact with -different `Viewer` components without the need for a `widget`. +different `Viewer` components without the need for a `widget`, and with +more specific effects than current pure commands. For example, `LayerEditor` contributions could take the currently active/selected `Layers` and edit the underlying data, while `LayerGenerator` @@ -141,6 +148,8 @@ extensible with these new contribution types and provide intuitive locations for both plugin developers to add their functionality, and users to find it. + + ## Detailed Description -- Add list of menus to `napari/constants/_menus.py`, warning for invalid IDs and new top level menus as per [#5153](https://github.com/napari/napari/pull/5153/files/e55ed333866384d85a780b8c2ab1591fab460300#diff-4ab84b59ab3d5cadbcf97fb21bd6547982d5b444251fd627a0b50deb51bec83b) -- Implement menu contribution interface that allows plugins to refer to their own plugin submenu -- Add functionality for opening widgets from a menu item -- Expose menu contribution reference in `npe2` -- Write menu contribution guide in `npe2` +Issue number [#7012](https://github.com/napari/napari/issues/7012) tracks the +current progress towards NAP-6 implementation, +and PR number [#7011](https://github.com/napari/napari/pull/7011) implements +the proposed contributable menus with some +limitations as described in the tracking issue. +When this NAP is finalized, the tracking issue contents should be copied to this +section. ## Backward Compatibility @@ -423,9 +529,9 @@ can simply maintain logic for migrating old IDs to new ones. If a contributable `napari` submenu is removed, this should be highlighted first by a deprecation warning. Once the submenu is deprecated, contributions that refer to this submenu should instead be placed in the higher level -menu. For example, if `Layers -> Generate -> Segmentation` is removed, +menu. For example, if `Layers -> Segment` is removed, existing contributions referring to this ID will be placed under -`Layers -> Generate`. +`Layers`. If a contributable `napari` top level menu is removed, this should be highlighted first by a deprecation warning. Before the submenu is deprecated, core developers @@ -441,40 +547,45 @@ in the plugin's submenu at the top level. ## Future Work -As mentioned above, a key feature to support rapid browsing for actions is the +**Command palette:** As mentioned above, a key feature to support rapid browsing for actions is the search functionality via the command palette. This is actively being worked on and is essential for navigation. -Once more contribution types are exposed for users, it's important that users +**Context dependent enablement:** Once more contribution types are exposed for users, it's important that users are aware why certain actions are disabled when the user doesn't meet the requisite context declared in the contribution's `enablement` clause. Since the syntax for declaring these contexts is strictly defined, we should be -able to surface information to suers about what is required for the action +able to surface information to users about what is required for the action to be enabled and functional. For example, an action could declare itself enabled only when a points layer *and* an image layer are selected. If the user has only selected an image layer, we could indicate the missing context to the user e.g. "Action takes a points and image layer, but no points layer is selected". -A desired attribute of these menu items is that users always know what +**Making actions predictable:** A desired attribute of these menu items is that users always know what will happen when they click a menu item. Does a widget open? Is the layer edited? Is a new layer added to the `Viewer`? Once more contribution types are exposed, we should be able to either add this information as metadata in the manifest file, or infer it from return type annotations of contribution commands, and also expose this to the user. -Finally, the number of actions in each menu is heavily dependent on +**Dynamic menus:** The number of actions in each menu is heavily dependent on the plugins installed in the user's environment. Given a complete set of contributable menus, we could dynamically inspect how many menu items each submenu contains, and group them appropriately for the user while limiting unnecessary depth. For example, if the user's environment has six plugins installed that each provide a `Watershed` segmentation, -we could display a `Layers -> Generate -> Segmentation -> Watershed` +we could display a `Layers -> Segment -> Watershed` submenu. If the user has just one `Watershed` segmentation plugin installed, this submenu would not appear. This would require very careful design to ensure the user still knows what to expect when they load up the `Viewer`. +**Location preferences:** One option to consider when moving/removing +menus is allowing plugin developers to declare a preference list of +menu locations, such that if one location is no longer available, +the menu item is placed in the next location on the preference list. + ## Alternatives The main alternative is the proposed `Tools` menu from [npe2 #161](https://github.com/napari/npe2/pull/161). @@ -499,7 +610,9 @@ interactions and plugin contributions e.g. multi canvas - **Jun 2 2022: npe2 #161** After further discussion (on zulip and in PR), this schema is identified as potentialy too limiting and there is mention that #160 may need to be reverted. A NAP is once again suggested as this is an influential decision with lots of opinions. - **Jun 13 2022: npe2 #161** is closed and #160 is reverted, with comment for follow up over in the napari repo. - **[Sep 30 2022: napari #5153](https://github.com/napari/napari/pull/5153)** opened with same list as in npe2, minimal discussion and input. -- **Oct 28 2022: napari #5153** discussion on core devs zulip stream begins. Developers mostly agree on the inidividual menu items but don't like how deep the `Tools` menu already is, and the lack of semantic meaning in its structure. +- **Oct 28 2022: napari #5153** discussion on core devs zulip stream begins. Developers mostly agree on the inidividual menu items but don't like how deep the `Tools` menu already is, and the lack of semantic meaning in its structure. +- **[Dec 22 2022: NAP6 PR](https://github.com/napari/docs/pull/77)** is opened and there is much discussion. Implementation is blocked by `app-model` work, so focus turns to that. +- **[Oct 04 2023: Hackathon](https://hackmd.io/fmKp0If5RkiwWIxYYRdKpg)** is held and Draga demos working branch of menu contributions. Core devs present discuss various outstanding items. This discussion is summarised in the linked notes. ## References and Footnotes