Document multiple commands single shortcut functionality (#10754)

* Add a comment to 'apputils:run-all-enabled' command * Add description and example of multi command shortcut functionality to documentation * Update user guide The JupyterLab Interface section * Resolve reStructuredText error messages * Add backquotes around apputils:run-all-enabled
jupyterlab · Aug 5, 2021 · 7ceeae9 · 7ceeae9
1 parent e3b3814
commit 7ceeae9
Show file tree

Hide file tree

Showing 3 changed files with 54 additions and 0 deletions.
diff --git a/docs/source/extension/extension_points.rst b/docs/source/extension/extension_points.rst
@@ -419,6 +419,31 @@ declaring default keyboard shortcuts for a command:
 
 Shortcuts added to the settings system will be editable by users.
 
+From Jupyterlab version 3.1 onwards, it is possible to execute multiple commands with a single shortcut. 
+This requires you to define a keyboard shortcut for ``apputils:run-all-enabled`` command:
+
+.. code:: json
+
+    {
+      "command": "apputils:run-all-enabled",
+      "keys": ["Accel T"],
+      "args": {
+          "commands": [
+              "my-command-1",
+              "my-command-2"
+          ],
+          "args": [
+              {},
+              {}
+            ]
+        },
+      "selector": "body"
+    }
+
+In this example ``my-command-1`` and ``my-command-2`` are passed in ``args`` 
+of ``apputils:run-all-enabled`` command as ``commands`` list.
+You can optionally pass the command arguemnts of ``my-command-1`` and ``my-command-2`` in ``args`` 
+of ``apputils:run-all-enabled`` command as ``args`` list.
 
 Launcher
 --------

diff --git a/docs/source/user/interface.rst b/docs/source/user/interface.rst
@@ -184,6 +184,33 @@ Keyboard Shortcuts in the Settings tab.
        <iframe src="https://www.youtube-nocookie.com/embed/rhW3kAExCik?rel=0&amp;showinfo=0" frameborder="0" allow="autoplay; encrypted-media" allowfullscreen></iframe>
     </div>
 
+To define a custom keyboard shortcut which runs more than one command, add a keyboard shortcut
+for ``apputils:run-all-enabled`` command in Keyboard Shortcuts advanced settings. The commands you
+wish to run are passed in the ``args`` argument as a list of strings:
+
+.. code:: json
+
+    {
+      "shortcuts": [
+        {
+          "command": "apputils:run-all-enabled",
+          "keys": [
+            "Accel T"
+          ],
+          "args": {
+            "commands": [
+              "docmanager:save",
+              "application:close"
+            ]
+          },
+          "selector": "body"
+        }
+      ]
+    }
+
+In this example ``docmanager:save`` and ``application:close`` commands are mapped to ``Accel T``. 
+The commands are run in succession when you use the shortcut.
+
 .. _editor-keymaps:
 
 You can also customize the :ref:`text editor <file-editor>` to use vim, emacs, or Sublime Text

diff --git a/packages/apputils-extension/src/index.ts b/packages/apputils-extension/src/index.ts
@@ -571,6 +571,8 @@ const utilityCommands: JupyterFrontEndPlugin<void> = {
       }
     });
 
+    // Add a command for taking lists of commands and command arguments
+    // and running all the enabled commands.
     commands.addCommand(CommandIDs.runAllEnabled, {
       label: trans.__('Run All Enabled Commands Passed as Args'),
       execute: async args => {