docs/notebooks/Starters.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "hide_input": true
   },
   "outputs": [],
   "source": [
    "import graphviz\n",
    "import IPython\n",
    "\n",
    "\n",
    "@IPython.core.magic.register_line_cell_magic\n",
    "def dot(line, cell):\n",
    "    return graphviz.Source(cell)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## For Starters\n",
    "\n",
    "The basic idea of a starter is:\n",
    "\n",
    "> - **pick a destination** in the _JupyterLab File Browser_\n",
    "> - **click a button** in the _JupyterLab Launcher_\n",
    "> - **see useful files**\n",
    "\n",
    "A slightly more accurate version is:\n",
    "\n",
    "> - configure via\n",
    ">   [traitlets](https://jupyter-notebook.readthedocs.io/en/stable/config.html)\n",
    "> - advertise to JupyterLab via the [REST API](./REST%20API.ipynb)\n",
    "> - display in the _JupyterLab Launcher_\n",
    "> - **click a button** in the _JupyterLab Launcher_\n",
    ">   - or immediately start with a [Starter Tree URL](#Starter-Tree-URL)\n",
    "> - zero or more (but usually one) times:\n",
    ">   - gather more information from the user via\n",
    ">     [react-jsonschema-form](https://react-jsonschema-form.readthedocs.io)\n",
    ">   - perform further processing\n",
    ">   - copy files via the\n",
    ">     [Contents API](https://jupyter-notebook.readthedocs.io/en/stable/extending/contents.html)\n",
    ">   - **see useful files** in the _JupyterLab File Browser_\n",
    ">   - run _JupyterLab Commands_ to do other things to JupyterLab\n",
    "\n",
    "Which of these steps a particular starter performs depends primarily on its type."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Types of Starters"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Copy\n",
    "\n",
    "> `\"type\": \"copy\"`\n",
    ">\n",
    "> `\"src\": \"<an absolute or relative path>\"`\n",
    "\n",
    "The simplest starter, `copy`, just... copies. It can copy a single file, or a directory\n",
    "of files (and subdirectories). The `src` attribute tells the starter where to get the\n",
    "files."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "hide_input": true
   },
   "outputs": [],
   "source": [
    "%%dot\n",
    "digraph g { compound=true layout=dot rankdir=TB\n",
    "    node[shape=none fontname=\"sans-serif\"]\n",
    "    graph[fontname=\"sans-serif\" fontcolor=\"grey\" color=\"none\" fillcolor=\"#eeeeee\" style=filled]\n",
    "    label=\"a notional execution of a copy starter\"\n",
    "    subgraph cluster_files { label=\"Your Files\"\n",
    "        files\n",
    "    }\n",
    "    \n",
    "    subgraph cluster_server { label=\"Notebook Server\"\n",
    "        get[label=\"/starters\" fontname=monospace]\n",
    "        post[label=\"/starters/{:name}/{:path}\" fontname=monospace]\n",
    "        contents\n",
    "    }\n",
    "\n",
    "    subgraph cluster_lab { label=\"JupyterLab\"\n",
    "        launcher\n",
    "    }\n",
    "    \n",
    "    get -> launcher[label=①]\n",
    "    launcher -> post[label=②]\n",
    "    post -> contents[label=③]\n",
    "    contents -> files[label=④]\n",
    "    files -> contents[label=⑤]\n",
    "    contents -> post[label=⑥]\n",
    "    post -> launcher[label=⑦]\n",
    "    launcher -> launcher[label=⑧]\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`copy`, like all the starters, makes use of the\n",
    "[Contents API](https://jupyter-notebook.readthedocs.io/en/stable/extending/contents.html)\n",
    "directly. Existing files will _not_ be overwritten."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Python\n",
    "\n",
    "> `\"type\": \"python\"`\n",
    ">\n",
    "> `\"callable\": \"<a dotted notation python function>\"`\n",
    "\n",
    "A Python Starter is a function. This type has the fewest limitations, as it has full\n",
    "access to the `StarterManager` (and by extension, it's `parent`, the `NotebookApp`).\n",
    "This powers both the [Cookiecutter](#Cookiecutter) the [Notebook](#Notebook) starters,\n",
    "with the latter directly using the notebook server's _Kernel Manager_ to start\n",
    "short-lifespan kernels."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "hide_input": true
   },
   "outputs": [],
   "source": [
    "%%dot\n",
    "digraph g { compound=true layout=dot rankdir=TB\n",
    "    node[shape=none fontname=\"sans-serif\"]\n",
    "    graph[fontname=\"sans-serif\" fontcolor=\"grey\" color=\"none\" fillcolor=\"#eeeeee\" style=filled]\n",
    "    label=\"a notional execution of a python starter\"\n",
    "    subgraph cluster_files { label=\"Your Files\"\n",
    "        files\n",
    "    }\n",
    "    \n",
    "    subgraph cluster_server { label=\"Notebook Server\"\n",
    "        get[label=\"/starters\" fontname=monospace]\n",
    "        post[label=\"/starters/{:name}/{:path}\" fontname=monospace]\n",
    "        contents\n",
    "        callable             \n",
    "    }\n",
    "\n",
    "    subgraph cluster_lab { label=\"JupyterLab\"\n",
    "        launcher\n",
    "    }\n",
    "    \n",
    "    get -> launcher[label=①]\n",
    "    launcher -> post[label=②]\n",
    "    post -> callable[label=③]\n",
    "    callable -> contents[label=④]\n",
    "    contents -> files[label=⑤]\n",
    "    files -> contents[label=⑥]\n",
    "    contents -> callable[label=⑦]\n",
    "    callable -> post[label=⑧]\n",
    "    post -> launcher[label=⑨]\n",
    "    launcher -> launcher[label=⑩]\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Notebook\n",
    "\n",
    "> `\"type\": \"notebook\"`\n",
    "\n",
    "A notebook can be a starter. Each starter run gets its own, private kernel which can\n",
    "persist between interactions with the user. Communication with the server manager is\n",
    "handled through manipulating a copy of the notebook, specfically the notebook metadata.\n",
    "The advantages of this approach over the Python starter is:\n",
    "\n",
    "- works with **any installed kernel**\n",
    "- **state is maintained** between successive re-executions\n",
    "- `jupyterlab-starters` provides **authoring support** for editing and validating the\n",
    "  starter"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "hide_input": true
   },
   "outputs": [],
   "source": [
    "%%dot\n",
    "digraph g { compound=true layout=dot rankdir=TB title=\"woooo\"\n",
    "    node[shape=none fontname=\"sans-serif\"]\n",
    "    graph[fontname=\"sans-serif\" fontcolor=\"grey\" color=\"none\" fillcolor=\"#eeeeee\" style=filled]\n",
    "    label=\"a notional execution of a notebook starter\"\n",
    "    subgraph cluster_files { label=\"Your Files\"\n",
    "        files\n",
    "    }\n",
    "    \n",
    "    subgraph cluster_server { label=\"Notebook Server\"\n",
    "        get[label=\"/starters\" fontname=monospace]\n",
    "        post[label=\"/starters/cookiecutter/{:path}\" fontname=monospace]\n",
    "        contents\n",
    "        kernel\n",
    "        tmpdir\n",
    "    }\n",
    "\n",
    "    subgraph cluster_lab { label=\"JupyterLab\"\n",
    "        launcher\n",
    "        form1[label=\"initial form\"]\n",
    "        form2[label=\"dynamic form\"]\n",
    "    }\n",
    "\n",
    "    get -> launcher[label=①]\n",
    "    launcher -> form1[label=②]\n",
    "    form1 -> post[label=③]\n",
    "    post -> tmpdir[label=④]\n",
    "    tmpdir -> post[label=⑤]\n",
    "    tmpdir -> kernel[label=⑥]\n",
    "    kernel -> tmpdir[label=⑦]\n",
    "    post -> form2[label=⑧]\n",
    "    form2 -> post[label=⑨]\n",
    "    post -> tmpdir[label=⑩]\n",
    "    tmpdir -> kernel[label=⑪]\n",
    "    kernel -> tmpdir[label=⑫]\n",
    "    tmpdir -> contents[label=⑬]\n",
    "    contents -> files[label=⑭]\n",
    "    files -> contents[label=⑮]\n",
    "    contents -> post[label=⑯]\n",
    "    post -> launcher[label=⑰]\n",
    "    launcher -> launcher[label=⑲]\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Built-ins"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Cookiecutter\n",
    "\n",
    "The cookiecutter starter will be available if `cookiecutter` is\n",
    "[installed](./Users.ipynb#Cookiecutter) in the same Python environment as the `notebook`\n",
    "server.\n",
    "\n",
    "> Additionally, if available, `importlib_metadata` will be used to list the (previously)\n",
    "> curated list of community-contributed cookiecutters. It is now recommended to search\n",
    "> for them directly on GitHub by\n",
    "> [topic](https://github.com/topics/cookiecutter-template) or\n",
    "> [advanced search](https://github.com/search?utf8=%E2%9C%93&q=path%3A%2F+filename%3Acookiecutter.json).\n",
    "\n",
    "One of the original motivations for _Jupyter Starters_ was a way to provide a\n",
    "convenient, consistent, web-based experience for the\n",
    "[cookiecutter](https://cookiecutter.rtfd.io) ecosystem. Briefly, a cookiecutter is:\n",
    "\n",
    "> - a repository, zip archive, or directory that contains\n",
    ">   - `cookiecutter.json`\n",
    ">   - a (potentially nested) directory that uses\n",
    ">     [Jinja2](https://jinja.palletsprojects.com) to describe file names and contents\n",
    "\n",
    "What they may lack in dynamism, the make up for in consistency and robustness."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "hide_input": true
   },
   "outputs": [],
   "source": [
    "%%dot\n",
    "digraph g { compound=true layout=dot rankdir=TB title=\"woooo\"\n",
    "    node[shape=none fontname=\"sans-serif\"]\n",
    "    graph[fontname=\"sans-serif\" fontcolor=\"grey\" color=\"none\" fillcolor=\"#eeeeee\" style=filled]\n",
    "    label=\"a notional execution of the cookiecutter starter\"\n",
    "    subgraph cluster_files { label=\"Your Files\"\n",
    "        files\n",
    "    }\n",
    "    \n",
    "    subgraph cluster_server { label=\"Notebook Server\"\n",
    "        get[label=\"/starters\" fontname=monospace]\n",
    "        post[label=\"/starters/cookiecutter/{:path}\" fontname=monospace]\n",
    "        contents\n",
    "        cookiecutter\n",
    "    }\n",
    "\n",
    "    subgraph cluster_lab { label=\"JupyterLab\"\n",
    "        launcher\n",
    "        form1[label=\"template form\"]\n",
    "        form2[label=\"cookiecutter form\"]\n",
    "    }\n",
    "    get -> launcher[label=①]\n",
    "    launcher -> form1[label=②]\n",
    "    form1 -> post[label=③]\n",
    "    post -> cookiecutter[label=④]\n",
    "    cookiecutter -> git[label=⑤]\n",
    "    git -> cookiecutter[label=⑥]\n",
    "    cookiecutter -> post[label=⑧]\n",
    "    post -> form2[label=⑨]\n",
    "    form2 -> post[label=⑩]\n",
    "    post -> cookiecutter[label=⑪]\n",
    "    cookiecutter -> contents[label=⑫]\n",
    "    contents -> files[label=⑬]\n",
    "    files -> contents[label=⑭]\n",
    "    contents -> post[label=⑮]\n",
    "    post -> launcher[label=⑯]\n",
    "    launcher -> launcher[label=⑰]\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Under the hood, the cookiecutter starter is implemented as a [Python starter](#Python),\n",
    "and can be seen as tutorial in how to create a starter from a complex piece of existing\n",
    "functionality."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Extras"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Starter Tree URL\n",
    "\n",
    "By specifying a special URL when starting JupyterLab, you can immediately start a\n",
    "Starter, without requiring the launcher. The pattern is:\n",
    "\n",
    "```\n",
    "{:protocol}://{:host}:{:port}{:base-url}/lab{:whatever}?starter/{:starter-name}{:starter-path}\n",
    "```\n",
    "\n",
    "For example:\n",
    "\n",
    "```\n",
    "http://localhost:8888/lab?starter=cookiecutter/\n",
    "```\n",
    "\n",
    "On [Binder](https://mybinder.org), this path is determined by the `urlpath` `GET`\n",
    "parameter, for example:\n",
    "\n",
    "```\n",
    "https://mybinder.org/v2/gh/deathbeds/jupyterlab-starters/master?urlpath=lab%3Fstarter%2Fcookiecutter%2Fexamples%2F\n",
    "```"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.7.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}