From 9a61af599739bb036538c969bfeb48524f15c531 Mon Sep 17 00:00:00 2001 From: Nicholas Bollweg Date: Wed, 13 Sep 2023 09:40:43 -0500 Subject: [PATCH] some docs --- README.md | 47 +++++++++----------- examples/Notebook Tour.ipynb | 84 ++++++++++++++++++++++++++++++++++++ 2 files changed, 105 insertions(+), 26 deletions(-) create mode 100644 examples/Notebook Tour.ipynb diff --git a/README.md b/README.md index f877ee1..d8bea31 100644 --- 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,16 +125,14 @@ 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": [] } } ``` @@ -145,17 +140,17 @@ An example `overrides.json` might look like: [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 new file mode 100644 index 0000000..53145aa --- /dev/null +++ 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 +}