alphabetized existing extension point docs

docs/source/developer/extension_points.rst

@@ -17,9 +17,13 @@ and more detailed descriptions of their public APIs may be found in the
     :local:
     :depth: 1
 
+
 Commands
 ~~~~~~~~
 
+Add a Command to the Command Registry
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 Perhaps the most common way to add functionality to JupyterLab is via commands.
 These are lightweight objects that include a function to execute combined with
 additional metadata, including how they are labeled and when they are to be enabled.
@@ -68,10 +72,10 @@ After a command has been added to the application command registry
 you can add them to various places in the application user interface,
 where they will be rendered using the metadata you provided.
 
-Command Palette
-~~~~~~~~~~~~~~~
+Add a Command to the Command Palette
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-In order to add a command to the command palette, you need to request the
+In order to add an existing, registered command to the command palette, you need to request the
 ``ICommandPalette`` token in your extension.
 Here is an example showing how to add a command to the command palette (given by ``palette``):
 
@@ -95,114 +99,6 @@ Your command ``label`` function can then check the ``args`` it is provided for `
 and return a different label in that case.
 This can be useful to make a single command flexible enough to work in multiple contexts.
 
-Main Menu
-~~~~~~~~~
-
-There are three main ways to extend JupyterLab's main menu.
-
-1. You can add your own menu to the menu bar.
-2. You can add new commands to the existing menus.
-3. You can register your extension with one of the existing semantic menu items.
-
-In all three cases, you should request the ``IMainMenu`` token for your extension.
-
-Adding a New Menu
-^^^^^^^^^^^^^^^^^
-
-To add a new menu to the menu bar, you need to create a new
-`Lumino menu <https://jupyterlab.github.io/lumino/widgets/classes/menu.html>`__.
-
-You can then add commands to the menu in a similar way to the command palette,
-and add that menu to the main menu bar:
-
-.. code:: typescript
-
-    const menu = new Menu({ commands: app.commands });
-    menu.addItem({
-      command: commandID,
-      args: {},
-    });
-
-    mainMenu.addMenu(menu, { rank: 40 });
-
-As with the command palette, you can optionally pass in ``args`` to customize the
-rendering and execution behavior of the command in the menu context.
-
-
-Adding a New Command to an Existing Menu
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-In many cases you will want to add your commands to the existing JupyterLab menus
-rather than creating a separate menu for your extension.
-Because the top-level JupyterLab menus are shared among many extensions,
-the API for adding items is slightly different.
-In this case, you provide a list of commands and a rank,
-and these commands will be displayed together in a separate group within an existing menu.
-
-For instance, to add a command group with ``firstCommandID`` and ``secondCommandID``
-to the File menu, you would do the following:
-
-.. code:: typescript
-
-    mainMenu.fileMenu.addGroup([
-      {
-        command: firstCommandID,
-      },
-      {
-        command: secondCommandID,
-      }
-    ], 40 /* rank */);
-
-
-Registering a Semantic Menu Item
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-There are some commands in the JupyterLab menu system that are considered
-common and important enough that they are treated differently.
-
-For instance, we anticipate that many activities may want to provide a command
-to close themselves and perform some cleanup operation (like closing a console and shutting down its kernel).
-Rather than having a proliferation of similar menu items for this common operation
-of "closing-and-cleanup", we provide a single command that can adapt itself to this use case,
-which we term a "semantic menu item".
-For this example, it is the File Menu ``closeAndCleaners`` set.
-
-Here is an example of using the ``closeAndCleaners`` semantic menu item:
-
-.. code:: typescript
-
-    mainMenu.fileMenu.closeAndCleaners.add({
-      tracker,
-      action: 'Shutdown',
-      name: 'My Activity',
-      closeAndCleanup: current => {
-        current.close();
-        return current.shutdown();
-      }
-    });
-
-In this example, ``tracker`` is a :ref:`widget-tracker`, which allows the menu
-item to determine whether to delegate the menu command to your activity,
-``name`` is a name given to your activity in the menu label,
-``action`` is a verb given to the cleanup operation in the menu label,
-and ``closeAndCleanup`` is the actual function that performs the cleanup operation.
-So if the current application activity is held in the ``tracker``,
-then the menu item will show ``Shutdown My Activity``, and delegate to the
-``closeAndCleanup`` function that was provided.
-
-More examples for how to register semantic menu items are found throughout the JupyterLab code base.
-The available semantic menu items are:
-
-- ``IEditMenu.IUndoer``: an activity that knows how to undo and redo.
-- ``IEditMenu.IClearer``: an activity that knows how to clear its content.
-- ``IEditMenu.IGoToLiner``: an activity that knows how to jump to a given line.
-- ``IFileMenu.ICloseAndCleaner``: an activity that knows how to close and clean up after itself.
-- ``IFileMenu.IConsoleCreator``: an activity that knows how to create an attached code console for itself.
-- ``IHelpMenu.IKernelUser``: an activity that knows how to get a related kernel session.
-- ``IKernelMenu.IKernelUser``: an activity that can perform various kernel-related operations.
-- ``IRunMenu.ICodeRunner``: an activity that can run code from its content.
-- ``IViewMenu.IEditorViewer``: an activity that knows how to set various view-related options on a text editor that it owns.
-
 
 Context Menu
 ~~~~~~~~~~~~
@@ -230,6 +126,65 @@ The selector can be any valid CSS selector, and may target your own UI elements,
 A list of CSS selectors currently used by context menu commands is given in :ref:`css-selectors`.
 
 
+.. _copy_shareable_link:
+
+Copy Shareable Link
+~~~~~~~~~~~~~~~~~~~
+
+The file browser provides a context menu item "Copy Shareable Link". The
+desired behavior will vary by deployment and the users it serves. The file
+browser supports overriding the behavior of this item.
+
+.. code:: typescript
+
+   import {
+     IFileBrowserFactory
+   } from '@jupyterlab/filebrowser';
+
+   import {
+     JupyterFrontEnd, JupyterFrontEndPlugin
+   } from '@jupyterlab/application';
+
+
+   const shareFile: JupyterFrontEndPlugin<void> = {
+     activate: activateShareFile,
+     id: commandID,
+     requires: [IFileBrowserFactory],
+     autoStart: true
+   };
+
+   function activateShareFile(
+     app: JupyterFrontEnd,
+     factory: IFileBrowserFactory
+   ): void {
+     const { commands } = app;
+     const { tracker } = factory;
+
+     commands.addCommand('filebrowser:share-main', {
+       execute: () => {
+         const widget = tracker.currentWidget;
+         if (!widget) {
+           return;
+         }
+         const path = encodeURI(widget.selectedItems().next().path);
+         // Do something with path.
+       },
+       isVisible: () =>
+         tracker.currentWidget &&
+         toArray(tracker.currentWidget.selectedItems()).length === 1,
+       iconClass: 'jp-MaterialIcon jp-LinkIcon',
+       label: 'Copy Shareable Link'
+     });
+   }
+
+Note that before enabling this plugin in the usual way, you must *disable* the
+default plugin provided by the built-in file browser.
+
+.. code:: bash
+
+   jupyter labextension disable @jupyterlab/filebrowser-extension:share-file
+
+
 Keyboard Shortcuts
 ~~~~~~~~~~~~~~~~~~
 
@@ -313,6 +268,115 @@ and then adds the terminal to the right area:
     });
 
 
+Main Menu
+~~~~~~~~~
+
+There are three main ways to extend JupyterLab's main menu.
+
+1. You can add your own menu to the menu bar.
+2. You can add new commands to the existing menus.
+3. You can register your extension with one of the existing semantic menu items.
+
+In all three cases, you should request the ``IMainMenu`` token for your extension.
+
+Adding a New Menu
+^^^^^^^^^^^^^^^^^
+
+To add a new menu to the menu bar, you need to create a new
+`Lumino menu <https://jupyterlab.github.io/lumino/widgets/classes/menu.html>`__.
+
+You can then add commands to the menu in a similar way to the command palette,
+and add that menu to the main menu bar:
+
+.. code:: typescript
+
+    const menu = new Menu({ commands: app.commands });
+    menu.addItem({
+      command: commandID,
+      args: {},
+    });
+
+    mainMenu.addMenu(menu, { rank: 40 });
+
+As with the command palette, you can optionally pass in ``args`` to customize the
+rendering and execution behavior of the command in the menu context.
+
+
+Adding a New Command to an Existing Menu
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In many cases you will want to add your commands to the existing JupyterLab menus
+rather than creating a separate menu for your extension.
+Because the top-level JupyterLab menus are shared among many extensions,
+the API for adding items is slightly different.
+In this case, you provide a list of commands and a rank,
+and these commands will be displayed together in a separate group within an existing menu.
+
+For instance, to add a command group with ``firstCommandID`` and ``secondCommandID``
+to the File menu, you would do the following:
+
+.. code:: typescript
+
+    mainMenu.fileMenu.addGroup([
+      {
+        command: firstCommandID,
+      },
+      {
+        command: secondCommandID,
+      }
+    ], 40 /* rank */);
+
+
+Registering a Semantic Menu Item
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+There are some commands in the JupyterLab menu system that are considered
+common and important enough that they are treated differently.
+
+For instance, we anticipate that many activities may want to provide a command
+to close themselves and perform some cleanup operation (like closing a console and shutting down its kernel).
+Rather than having a proliferation of similar menu items for this common operation
+of "closing-and-cleanup", we provide a single command that can adapt itself to this use case,
+which we term a "semantic menu item".
+For this example, it is the File Menu ``closeAndCleaners`` set.
+
+Here is an example of using the ``closeAndCleaners`` semantic menu item:
+
+.. code:: typescript
+
+    mainMenu.fileMenu.closeAndCleaners.add({
+      tracker,
+      action: 'Shutdown',
+      name: 'My Activity',
+      closeAndCleanup: current => {
+        current.close();
+        return current.shutdown();
+      }
+    });
+
+In this example, ``tracker`` is a :ref:`widget-tracker`, which allows the menu
+item to determine whether to delegate the menu command to your activity,
+``name`` is a name given to your activity in the menu label,
+``action`` is a verb given to the cleanup operation in the menu label,
+and ``closeAndCleanup`` is the actual function that performs the cleanup operation.
+So if the current application activity is held in the ``tracker``,
+then the menu item will show ``Shutdown My Activity``, and delegate to the
+``closeAndCleanup`` function that was provided.
+
+More examples for how to register semantic menu items are found throughout the JupyterLab code base.
+The available semantic menu items are:
+
+- ``IEditMenu.IUndoer``: an activity that knows how to undo and redo.
+- ``IEditMenu.IClearer``: an activity that knows how to clear its content.
+- ``IEditMenu.IGoToLiner``: an activity that knows how to jump to a given line.
+- ``IFileMenu.ICloseAndCleaner``: an activity that knows how to close and clean up after itself.
+- ``IFileMenu.IConsoleCreator``: an activity that knows how to create an attached code console for itself.
+- ``IHelpMenu.IKernelUser``: an activity that knows how to get a related kernel session.
+- ``IKernelMenu.IKernelUser``: an activity that can perform various kernel-related operations.
+- ``IRunMenu.ICodeRunner``: an activity that can run code from its content.
+- ``IViewMenu.IEditorViewer``: an activity that knows how to set various view-related options on a text editor that it owns.
+
+
 Status Bar
 ~~~~~~~~~~
 
@@ -359,61 +423,3 @@ Widget tracker tokens are provided for many activities in JupyterLab, including
 notebooks, consoles, text files, mime documents, and terminals.
 If you are adding your own activities to JupyterLab, you might consider providing
 a ``WidgetTracker`` token of your own, so that other extensions can make use of it.
-
-.. _copy_shareable_link:
-
-Copy Shareable Link
-~~~~~~~~~~~~~~~~~~~
-
-The file browser provides a context menu item "Copy Shareable Link". The
-desired behavior will vary by deployment and the users it serves. The file
-browser supports overriding the behavior of this item.
-
-.. code:: typescript
-
-   import {
-     IFileBrowserFactory
-   } from '@jupyterlab/filebrowser';
-
-   import {
-     JupyterFrontEnd, JupyterFrontEndPlugin
-   } from '@jupyterlab/application';
-
-
-   const shareFile: JupyterFrontEndPlugin<void> = {
-     activate: activateShareFile,
-     id: commandID,
-     requires: [IFileBrowserFactory],
-     autoStart: true
-   };
-
-   function activateShareFile(
-     app: JupyterFrontEnd,
-     factory: IFileBrowserFactory
-   ): void {
-     const { commands } = app;
-     const { tracker } = factory;
-
-     commands.addCommand('filebrowser:share-main', {
-       execute: () => {
-         const widget = tracker.currentWidget;
-         if (!widget) {
-           return;
-         }
-         const path = encodeURI(widget.selectedItems().next().path);
-         // Do something with path.
-       },
-       isVisible: () =>
-         tracker.currentWidget &&
-         toArray(tracker.currentWidget.selectedItems()).length === 1,
-       iconClass: 'jp-MaterialIcon jp-LinkIcon',
-       label: 'Copy Shareable Link'
-     });
-   }
-
-Note that before enabling this plugin in the usual way, you must *disable* the
-default plugin provided by the built-in file browser.
-
-.. code:: bash
-
-   jupyter labextension disable @jupyterlab/filebrowser-extension:share-file