Add user tours in Advanced Settings (#17)

* add user tours * fix settings package name * unify types, split steps/options * refactor into mutiple plugins * revert some signature changes * update tests for multiple plugins * update react-joyride to 2.3, fix some typing issues * refactor new user stuff into separate manager, expose token * typos * rename ExtendedPlacement to StepPlacement * Update src/userTourManager.ts * add cli docs * fix rejection
jupyterlab-contrib · May 9, 2021 · f1913ae · f1913ae
1 parent f2d53e7
commit f1913ae
Show file tree

Hide file tree

Showing 12 changed files with 1,346 additions and 92 deletions.
diff --git a/.gitignore b/.gitignore
@@ -111,3 +111,6 @@ dmypy.json
 # OSX files
 .DS_Store
 coverage/
+
+# logs
+*.log
diff --git a/README.md b/README.md
@@ -10,11 +10,26 @@ A JupyterLab UI Tour based on [react-joyride](https://docs.react-joyride.com).
 
 ![demo](https://raw.githubusercontent.com/jupyterlab-contrib/jupyterlab-tour/master/doc/tourDemo.gif)
 
+## Install
+
+```bash
+pip install jupyterlab-tour
+```
+
+or
+
+```bash
+conda install -c conda-forge jupyterlab-tour
+```
+
+## Features
+
 This extension has the following features:
 
 - Default tours:
   - Welcome tour
   - Notebook tour
+  - User-defined features in Settings
 - Toast proposing to start a tour - to experienced users the need to exit each time the tour.
 - If a tour has already be seen by the user, this is saved in the state database. So you can start tour on event only if the user have not seen it; e.g. the welcome tour is launched at JupyterLab start except if the user have seen it.
 
@@ -36,9 +51,70 @@ For JupyterLab 2.x, have look [there](https://github.com/jupyterlab-contrib/jupy
 
 > For developers, the API has changed between v3 (for JupyterLab 3) and v2 (for JupyterLab 2).
 
+## How to add a tour with Advanced Settings
+
+As a user of JupyterLab, after you've installed `jupyterlab-tour`, you can create
+your own _Tours_ as data.
+
+- Open the JupyterLab _Advanced Settings_ panel <kbd>Ctrl+,</kbd>
+- Select _Tours_ from list of settings groups
+- In the editor, create JSON(5) compatible with the
+  [react-joyride data model](https://docs.react-joyride.com/props)
+- The _Tour_ will be available from the _Help Menu_, as well as the _Command Palette_
+
+### A simple Tour
+
+For example, to show a glowing button on the Jupyter logo, which reveals an orange
+overlay when pressed:
+
+```json5
+// json5 can have comments
+{
+  "tours": [
+    {
+      "id": "my-tour",
+      "label": "My First Tour",
+      // steps are required, and have many, many options
+      "steps": [
+        {"target": "#jp-MainLogo", "content": "Look at this!"}
+      ],
+      // below here not required!
+      "options": {
+        "styles": {
+          "options": {
+            // you can use jupyterlab theme variables
+            "backgroundColor": "var(--jp-warn-color0)"
+          }
+        }
+      }
+    }
+  ]
+}
+```
+
+### Shipping a Tour to Binder
+
+On Binder, and elsewhere, you can store the above (_without_ comments) in
+an [overrides.json] file and put it in the _right place_,
+e.g. `{sys.prefix}/share/jupyter/lab/settings/overrides.json`. When JupyterLab is
+next opened, those overrides will become the defaults, and your tour will be available.
+
+An example `overrides.json` might look like:
+```json5
+{
+  "jupyterlab-tour:user-tours": {
+    "tours": [
+      // that tour up there!
+    ]
+  }
+}
+```
+
+[overrides.json]: https://jupyterlab.readthedocs.io/en/stable/user/directories.html#overrides-json
+
 ## How to add tour for my JupyterLab extension
 
-There are two methods to add a tour: the easiest is to use JupyterLab commands and the advanced version is to request this
+As an extension developer, there are two methods to add a tour: the easiest is to use JupyterLab commands and the advanced version is to request this
 extension token `ITourManager`.
 
 ### Add easily a tour
@@ -49,7 +125,7 @@ const { commands } = app;
 const tour = (await app.commands.execute('jupyterlab-tour:add', {
   tour: { // Tour must be of type ITour - see src/tokens.ts
     id: 'test-jupyterlab-tour:welcome',
-    label: 'Welcome Tour',    
+    label: 'Welcome Tour',
     hasHelpEntry: true,
     steps: [  // Step must be of type IStep - see src/tokens.ts
       {
@@ -66,7 +142,8 @@ const tour = (await app.commands.execute('jupyterlab-tour:add', {
         target: '#jp-main-dock-panel',
         title: 'Main Content'
       }
-    ]
+    ],
+    // can also define `options`
   }
 })) as ITour;
 if ( tour ) {
@@ -80,18 +157,41 @@ if ( tour ) {
 > One example is available on [Mamba navigator](https://github.com/mamba-org/gator/blob/master/packages/labextension/src/index.ts#L76).
 > Test it on [binder](https://mybinder.org/v2/gh/mamba-org/gator/master?urlpath=lab).
 
-## Install
+## Disabling the User and Default Tours
+
+If you _only_ wish to see the default _Welcome_ and _Notebook_ tours, or ones
+defined by users, they can be disabled via the command line or a well-known file.
+
+The examples below disable all tours not provided by third-party extensions.
+Adding `jupyterlab-tour:plugin` to either of these will disable tours altogether!
+
+### Disabling Tours from the Command Line
+
+From the command line, run:
 
 ```bash
-pip install jupyterlab-tour
+jupyter labextension disable "jupyterlab-tour:user-tours"
+jupyter labextension disable "jupyterlab-tour:default-tours"
 ```
 
-or
+### Disabling Tours with `pageConfig.json`
 
-```bash
-conda install -c conda-forge jupyterlab-tour
+Create a [pageConfig.json] and put it in _the right place_, e.g.
+`{sys.prefix}/etc/jupyter/labconfig/pageconfig.json` and add the plugin IDs to
+`disabledExtensions`.
+
+```json
+{
+  "disabledExtensions": {
+    "jupyterlab-tour:user-tours": true,
+    "jupyterlab-tour:default-tours": true,
+  }
+}
 ```
 
+[pageConfig.json]: https://jupyterlab.readthedocs.io/en/stable/user/directories.html#labconfig-directories
+
+
 ## Uninstall
 
 ```bash

diff --git a/package.json b/package.json
@@ -16,7 +16,8 @@
   "files": [
     "lib/**/*.{d.ts,eot,gif,html,jpg,js,js.map,json,png,svg,woff2,ttf}",
     "style/**/*.{css,eot,gif,html,jpg,json,png,svg,woff2,ttf}",
-    "style/index.js"
+    "style/index.js",
+    "schema/*.json"
   ],
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -49,6 +50,7 @@
     "@jupyterlab/apputils": "^3.0.0",
     "@jupyterlab/mainmenu": "^3.0.0",
     "@jupyterlab/notebook": "^3.0.0",
+    "@jupyterlab/settingregistry": "^3.0.0",
     "@jupyterlab/statedb": "^3.0.0",
     "@lumino/coreutils": "^1.5.3",
     "@lumino/disposable": "^1.4.3",
@@ -57,7 +59,7 @@
     "jupyterlab_toastify": "^4.1.2",
     "react": "^17.0.1",
     "react-dom": "^17.0.1",
-    "react-joyride": "^2.2.1"
+    "react-joyride": "^2.3.0"
   },
   "devDependencies": {
     "@babel/core": "^7.11.0",
@@ -67,7 +69,6 @@
     "@types/jest": "^26.0.0",
     "@types/react": "^17.0.0",
     "@types/react-dom": "^17.0.0",
-    "@types/react-joyride": "^2.0.5",
     "@typescript-eslint/eslint-plugin": "^2.27.0",
     "@typescript-eslint/parser": "^2.27.0",
     "eslint": "^7.5.0",
@@ -89,6 +90,7 @@
   ],
   "jupyterlab": {
     "extension": true,
+    "schemaDir": "schema",
     "outputDir": "jupyterlab_tour/labextension",
     "sharedPackages": {
       "jupyterlab_toastify": {