some docs

jupyterlab-contrib · Sep 13, 2023 · 9a61af5 · 9a61af5
1 parent aa8e74e
commit 9a61af5
Show file tree

Hide file tree

Showing 2 changed files with 105 additions and 26 deletions.
diff --git a/README.md b/README.md
@@ -33,20 +33,19 @@ This extension has the following features:
   - 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
+- Toast proposing to start a 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.
 
 > The state is cleaned if this extension is updated
 
 - Tooltip are styled using JupyterLab theming system
 - Commands to _add_ and _launch_ tours
-- Through the tour manager (`ITourManager` extension token), add, modify or delete a
-  tour
-- Connect to tour events through signals
-- Override the default style (and options) for the tour separately
+- Through the _Tour Manager_ (`ITourManager` extension token), add, modify or delete a
+  Tour
+- Connect to Tour events through signals
+- Override the default style (and options) for the Tour separately
 
 This extension is inspired by
 [@cdat/jupyterlab-tutorial](https://github.com/CDAT/jupyterlab-tutorial) licensed under
@@ -62,7 +61,7 @@ For JupyterLab 2.x, have look
 > For developers, the API has changed between v3 (for JupyterLab 3) and v2 (for
 > JupyterLab 2).
 
-## How to add a tour with Advanced Settings
+## 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.
@@ -101,21 +100,19 @@ overlay when pressed:
 }
 ```
 
-## How to add a tour to a Notebook
+## How to add a Tour to a Notebook
 
-The same JSON used to create a tour in _Advanced Settings_ can be added to a Notebook.
+The same JSON used to create a Tour in _Advanced Settings_ can be added to a Notebook.
 
 - Open the Notebook
 - Open the _Property Inspector_ sidebar (the "gears" icon)
 - Open _Advanced Tools_
 - Create a key in _Notebook Metadata_ like:
 
-```json5
+```json
 {
-  'jupyterlab-tour': {
-    tours: [
-      // that tour up there!
-    ]
+  "jupyterlab-tour": {
+    "tours": []
   }
 }
 ```
@@ -128,34 +125,32 @@ which will allow lauching one (or all) of the tours saved in the Notebook.
 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.
+opened, those overrides will become the defaults, and your Tour will be available.
 
 An example `overrides.json` might look like:
 
-```json5
+```json
 {
-  'jupyterlab-tour:user-tours': {
-    tours: [
-      // that tour up there!
-    ]
+  "jupyterlab-tour:user-tours": {
+    "tours": []
   }
 }
 ```
 
 [overrides.json]:
   https://jupyterlab.readthedocs.io/en/stable/user/directories.html#overrides-json
 
-## How to add tour for my JupyterLab extension
+## How to add Tour for my JupyterLab extension
 
 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 a tour with TypeScript
+### Add a Tour with TypeScript
 
 ```ts
 const { commands } = app;
-// Add a tour - returns the tour or null if something went wrong
+// Add a Tour - returns the Tour or null if something went wrong
 const tour = (await app.commands.execute('jupyterlab-tour:add', {
   tour: {
     // Tour must be of type ITour - see src/tokens.ts
@@ -185,7 +180,7 @@ const tour = (await app.commands.execute('jupyterlab-tour:add', {
 if (tour) {
   app.commands.execute('jupyterlab-tour:launch', {
     id: 'test-jupyterlab-tour:welcome',
-    force: false // Optional, if false the tour will start only if the user have not seen or skipped it
+    force: false // Optional, if false the Tour will start only if the user have not seen or skipped it
   });
 }
 ```

diff --git a/examples/Notebook Tour.ipynb b/examples/Notebook Tour.ipynb
@@ -0,0 +1,84 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "d173db05-a853-4676-9dc2-683cc7200fe5",
+   "metadata": {},
+   "source": [
+    "# Notebook Tour\n",
+    "\n",
+    "An `.ipynb` can store one or more Tours in notebook metadata. When populated, the tour can be started from a number of places:\n",
+    "- the pin icon in the _Notebook Toolbar_\n",
+    "- the _Help_ menu in the _Main Menu_\n",
+    "- the _Command Palette_ under _Launch a New Tour_"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "9c27102d-0c16-4a5c-b1e8-8c835db3a8ff",
+   "metadata": {},
+   "source": [
+    "## This Notebook's Tour\n",
+    "\n",
+    "This tour in this notebook works in both JupyterLab and Jupyter Notebook."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "f0af7aa3-de82-42f2-8502-63f42a4d721c",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import json\n",
+    "from pathlib import Path\n",
+    "from IPython.display import JSON, HTML\n",
+    "\n",
+    "nb = json.load(Path(\"Notebook Tour.ipynb\").open())\n",
+    "JSON(nb[\"metadata\"][\"jupyterlab-tour\"], expanded=True)"
+   ]
+  }
+ ],
+ "metadata": {
+  "jupyterlab-tour": {
+   "tours": [
+    {
+     "id": "my-tour",
+     "label": "My First Tour",
+     "options": {
+      "styles": {
+       "options": {
+        "backgroundColor": "var(--jp-warn-color0)"
+       }
+      }
+     },
+     "steps": [
+      {
+       "content": "Look at this!",
+       "target": "#jp-MainLogo, #jp-NotebookLogo"
+      }
+     ]
+    }
+   ]
+  },
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.11.5"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}