Update end-to-end walkthrough for JupyterCon 2023

Author: seeM

nbs/index.css

@@ -10,6 +10,10 @@ html {
   font-family: Inter, SF Pro Display, -apple-system, sans-serif;
 }
 
+h1, h2, h3 {
+  font-weight: normal;
+}
+
 body {
   background: var(--background);
   color: var(--foreground);

nbs/tutorials/images/jupyter-blank-terminal.png

@@ -64,30 +64,32 @@
     "4. nbdev\n",
     "5. Quarto\n",
     "\n",
-    "If you haven't worked with Python before, we recommend getting started with the [Anaconda Individual Edition](https://www.anaconda.com/products/individual) and using the conda package manager."
+    "If you haven't worked with Python before, we recommend getting started with the [Anaconda Individual Edition](https://www.anaconda.com/products/individual) and using the conda package manager.\n",
+    "\n",
+    "Note that you will only need to follow the steps in the installation section once per environment. If you create a new repo, you won't need to redo these."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Install Jupyter Notebook"
+    "### Install Jupyter Lab"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Launch a terminal and install Jupyter Notebook by entering:\n",
+    "Launch a terminal and install Jupyter Lab by entering:\n",
     "\n",
     "```sh\n",
-    "conda install notebook\n",
+    "conda install -c conda-forge jupyterlab\n",
     "```\n",
     "\n",
     "...or\n",
     "\n",
     "```sh\n",
-    "pip install notebook\n",
+    "pip install jupyterlab\n",
     "```\n",
     "\n",
     "...if you're using the pip package manager.\n",
@@ -97,30 +99,17 @@
     "You can now launch Jupyter by entering:\n",
     "\n",
     "```sh\n",
-    "jupyter notebook\n",
+    "jupyter lab\n",
     "```\n",
     "\n",
-    "This should open the Jupyter home page in a new browser tab:"
+    "This should open Jupyter Lab in a new browser tab:"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "![](images/jupyter-home-page.png){.px-1 .py-2 fig-align=\"center\" .border .rounded .shadow-sm}"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "::: {.callout-tip collapse=\"true\"}\n",
-    "\n",
-    "#### Why not Jupyter Lab?\n",
-    "\n",
-    "As Jupyter power users we still prefer Jupyter Notebook (with [customizations](#install-collapsible-headings-and-toc2)) over more feature-full alternatives like Jupyter Lab, VSCode, or PyCharm. We find Jupyter Notebook simpler, faster, and more robust.\n",
-    "\n",
-    ":::"
+    "![](images/jupyter-welcome.png){fig-align=\"center\"}"
    ]
   },
   {
@@ -134,18 +123,18 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The next step is to install nbdev itself. Jupyter Notebook comes with its own terminal, so we'll use that moving forward.\n",
+    "The next step is to install nbdev itself. Jupyter Lab comes with its own terminal, so we'll use that moving forward.\n",
     "\n",
-    "In the Jupyter home page (shown in the previous section), click the \"New\" dropdown on the right side, then \"Terminal\".\n",
+    "In the Launcher, scroll down to the \"Other\" section, then click \"Terminal\". If the Launcher isn't opened, you can open it by clicking \"File\" → \"New Launcher\".\n",
     "\n",
-    "A browser tab should open with a blank terminal:"
+    "A new tab should open with a blank terminal -- it might not look exactly the same, depending on how your shell is configured:"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "![](images/jupyter-blank-terminal.png){.pt-2 fig-align=\"center\" .border .rounded .shadow-sm}"
+    "![](images/jupyter-blank-terminal.png){fig-align=\"center\"}"
    ]
   },
   {
@@ -189,6 +178,36 @@
     "Your password may be requested at this point. Since nbdev is open source, you can read [the source code](https://github.com/fastai/nbdev/blob/master/nbdev/quarto.py) of this command to verify that it isn't doing anything malicious. Or, if you prefer, you may instead follow [Quarto's official installation instructions](https://quarto.org/docs/get-started/)."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Install Quarto Jupyter Lab extension"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Quarto provides its own [Jupyter Lab extension](https://quarto.org/docs/tools/jupyter-lab-extension.html) that allows it to render Quarto markdown content.\n",
+    "\n",
+    "For example, here is their notebook demonstrating some of its features:\n",
+    "\n",
+    "![](https://user-images.githubusercontent.com/261654/230087634-d5027ebc-8508-43b4-81c9-c4b7d6cfa738.png)\n",
+    "\n",
+    "Install the extension by entering:\n",
+    "\n",
+    "```sh\n",
+    "pip install jupyterlab-quarto\n",
+    "```\n",
+    "\n",
+    "Note that the `jupyterlab-quarto` package is not currently available via conda.\n",
+    "\n",
+    "---\n",
+    "\n",
+    "You're all setup and ready to go! Installing these tools may take some time, but you'll only need to do it once. Next, we'll setup an nbdev repo for your specific project."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -216,9 +235,9 @@
    "source": [
     "Create an empty GitHub repo using the convenient link [github.com/new](https://github.com/new). If you get stuck, you might find GitHub's [_Create a repo_](https://docs.github.com/en/get-started/quickstart/create-a-repo) page helpful.\n",
     "\n",
-    "Remember to add a description, since nbdev will use that later. Don't add a README file, .gitignore, or license file just yet.\n",
+    "Remember to add a description, since nbdev will use that later. Don't add a README file, .gitignore, or license just yet.\n",
     "\n",
-    "If you're using the web interface, it should look something like this before you click \"Create Repository\":"
+    "If you're using the web interface, it should look something like this (with your own repository name and descrpition) before you click \"Create Repository\":"
    ]
   },
   {
@@ -349,11 +368,38 @@
     "git add .\n",
     "git commit -m'Initial commit'\n",
     "git push\n",
-    "```\n",
-    "\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Enable GitHub Pages"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "nbdev hosts your docs on GitHub Pages---an excellent (and free!) way to host websites. "
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "::: {.callout-note}\n",
     "\n",
-    "### Enable GitHub Pages\n",
+    "nbdev uses GitHub Pages by default because its easily accessible. However, you can use any host you like.  See [these docs](../explanations/docs.ipynb#deploying-your-docs-on-other-platforms) for more information.\n",
     "\n",
+    ":::"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
     "You need to enable GitHub Pages for your repo by clicking on the \"Settings\" tab near the top-right of your repo page, then \"Pages\" on the left, then setting the \"Branch\" to \"gh-pages\", and finally clicking \"Save\".\n",
     "\n",
     "It should look similar to this after you click \"Save\":\n",
@@ -400,7 +446,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "If you see a red cross (❌), that means something failed. Click on the cross, then click *Details*, and you'll be able to see what failed. If you can't figure out what's wrong, search [the forum](https://forums.fast.ai/c/nbdev/48) in case someone else resolved the same issue, otherwise create a new post describing your issue in as much detail as you can, and we'll try our best to help you. Remember that including a link to an actual repo and/or GitHub Action is the best way for us to quickly identify what's wrong."
+    "If you see a red cross (❌), that means something failed. Click on the cross, then click \"Details\", and you'll be able to see what failed. If you can't figure out what's wrong, search [the forum](https://forums.fast.ai/c/nbdev/48) in case someone else resolved the same issue, otherwise create a new post describing your issue in as much detail as you can, and we'll try our best to help you. Remember that including a link to an actual repo and/or GitHub Action is the best way for us to quickly identify what's wrong."
    ]
   },
   {
@@ -423,13 +469,6 @@
     "We provide these basic workflows out-of-the-box, however, you can edit their corresponding YAML files in the `.github/workflows/` folder to your liking."
    ]
   },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "Note that you'll need to enable GitHub Pages for your repo before you can access your docs website. We'll do that now."
-   ]
-  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -441,14 +480,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "nbdev hosts your docs on GitHub Pages---an excellent (and free!) way to host websites. "
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "Head back to GitHub Actions and you should see a new workflow run: \"pages build and deployment\". As the name says, this workflow deploys your website contents to GitHub Pages."
+    "When you [enable GitHub Pages](#enable-github-pages) you should see a new workflow run: \"pages build and deployment\". As the name suggests, this workflow deploys your website contents to GitHub Pages."
    ]
   },
   {
@@ -472,17 +504,6 @@
     "![](images/nbdev-hello-world-site-initial.png){fig-align=\"center\" .border .rounded .shadow-sm}"
    ]
   },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "::: {.callout-note}\n",
-    "\n",
-    "nbdev uses GitHub Pages by default because its easily accessible. However, you can use any host you like.  See [these docs](../explanations/docs.ipynb#deploying-your-docs-on-other-platforms) for more information on this.\n",
-    "\n",
-    ":::"
-   ]
-  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -496,7 +517,7 @@
    "source": [
     "You now have a base nbdev repo with continuous integration and hosted documentation! Here's a recap of the steps you took:\n",
     "\n",
-    "- Created a GitHub repo\n",
+    "- Created a GitHub repo (with GitHub Pages enabled)\n",
     "- Initialised your repo with `nbdev_new`\n",
     "- Pushed to GitHub."
    ]
@@ -541,7 +562,7 @@
    "source": [
     "::: {.callout-note}\n",
     "\n",
-    "The [clean hook](#nbdev_clean-on-saving-notebooks-in-jupyter) currently only supports Jupyter Notebook and Jupyter Lab. If you're using another notebook editor, like VSCode or PyCharm, you might want to use [nbdev's pre-commit hooks](/tutorials/pre_commit.ipynb) as well.\n",
+    "The [clean hook](#nbdev_clean-on-saving-notebooks-in-jupyter) currently only supports Jupyter Notebook and Jupyter Lab. If you're using VSCode, you can try the [experimental nbdev VSCode extension](https://github.com/fastai/nbdev-vscode). Otherwise, you might also want to try [nbdev's pre-commit hooks](/tutorials/pre_commit.ipynb).\n",
     "\n",
     ":::"
    ]
@@ -563,7 +584,7 @@
    "source": [
     "::: {.callout-tip}\n",
     "\n",
-    "nbdev hooks works on _any_ git repo, even if it doesn't use the broader nbdev system.\n",
+    "nbdev's git hooks work on _any_ git repo, even if it doesn't use the broader nbdev system.\n",
     "\n",
     ":::"
    ]
@@ -614,7 +635,7 @@
     "\n",
     "This is the recommended way to make a Python package importable from anywhere in your current environment:\n",
     "\n",
-    "- `-e` -- short for \"editable\", lets you immediately use changes made to your package during development.\n",
+    "- `-e` -- short for \"editable\", lets you immediately use changes made to your package without having to reinstall, which is convenient for development.\n",
     "- `.` -- refers to the current directory.\n",
     "- `[dev]` -- includes \"development\" requirements: other packages that your notebooks use solely for documentation or testing."
    ]
@@ -690,7 +711,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Now, run `jupyter notebook`, and click `00_core.ipynb` (note: if you started this tutorial using `nbdev_new` then this file will be in the `nbs` folder). You don't *have* to start your notebook names with a number, but we find it helpful to show the order that your project should be read in -- even though it could have been created in a different order."
+    "Now, open the `nbs/00_core.ipynb` file (generated by running `nbdev_new` earlier) in Jupyter. You don't *have* to start your notebook names with a number, but we find it helpful to show the order that your project should be read in -- even though it could have been created in a different order."
    ]
   },
   {
@@ -836,8 +857,6 @@
       "\n",
       "---\n",
       "\n",
-      "[source](https://github.com/fastai/nbdevblob/master/nbdev/tutorial.py#L7){target=\"_blank\" style=\"float:right; font-size:smaller\"}\n",
-      "\n",
       "### say_hello\n",
       "\n",
       ">      say_hello (to)\n",
@@ -922,7 +941,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "assert say_hello(\"Hamel\")==\"Hello Hamel!\""
+    "assert say_hello(\"Hamel\") == \"Hello Hamel!\""
    ]
   },
   {
@@ -974,7 +993,7 @@
     {
      "data": {
       "image/svg+xml": [
-       "<svg xmlns=\"http://www.w3.org/2000/svg\" height=\"100\"><circle cx=\"50\" cy=\"50\" r=\"40\"/></svg>\n"
+       "<svg xmlns=\"http://www.w3.org/2000/svg\" height=\"100\"><circle cx=\"50\" cy=\"50\" r=\"40\"/></svg>"
       ],
       "text/plain": [
        "<IPython.core.display.SVG object>"
@@ -1001,10 +1020,10 @@
    "source": [
     "Before commiting your changes to GitHub we recommend running `nbdev_prepare` in the terminal, which bundles the following commands:\n",
     "\n",
-    "- `nbdev_export`: Builds the .py modules from Jupyter notebooks\n",
+    "- `nbdev_export`: Builds the `.py` modules from Jupyter notebooks\n",
     "- `nbdev_test`: Tests your notebooks\n",
-    "- `nbdev_clean`: Cleans your notebooks to get rid of extreanous output for Github\n",
-    "- `nbdev_readme`: Updates README.md from your index notebook."
+    "- `nbdev_clean`: Cleans your notebooks to get rid of extreanous output for git\n",
+    "- `nbdev_readme`: Updates your repo's `README.md` file from your index notebook."
    ]
   },
   {
@@ -1018,14 +1037,14 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Now you're ready to create your documentation home page and README.md file; these are both generated automatically from index.ipynb. Open the Jupyter Notebook home page, then click on index.ipynb to open it."
+    "Now you're ready to personalize your documentation home page and `README.md` file; these are both generated automatically from index.ipynb. Open Jupyter, then click on `nbs/index.ipynb` to open it."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "We recommend including a longer description about what your package does, how to install it, and how to use it (with a few examples which import and use your package). Remember, examples can be code cells with real outputs rather than plain markdown text."
+    "We recommend including a longer description about what your package does, how to install it, and how to use it (with a few examples which import and use your package). Remember, examples can be code cells with real outputs rather than plain markdown text -- they'll double as tests too!"
    ]
   },
   {
@@ -1043,7 +1062,7 @@
     "\n",
     "```sh\n",
     "git add .\n",
-    "git commit -m'Add `say_hello`; update index' # Update this text with your own message\n",
+    "git commit -m 'Add `say_hello`; update index' # Update this text with your own message\n",
     "git push\n",
     "```\n",
     "\n",
@@ -1066,12 +1085,12 @@
     "- Installed hooks for git-friendly notebooks with `nbdev_install_hooks`\n",
     "- Installed your package with `pip install -e '.[dev]'`\n",
     "- Previewed your docs with `nbdev_preview`\n",
-    "- Added your own frontmatter, function, tests, and docs to 00_core.ipynb\n",
+    "- Added your own frontmatter, function, tests, and docs to `nbs/00_core.ipynb`\n",
     "- Prepared your changes with `nbdev_prepare`\n",
-    "- Updated index.ipynb with your own information\n",
+    "- Updated `nbs/index.ipynb` with your own information\n",
     "- Pushed to GitHub.\n",
     "\n",
-    "Read on to learn about more advanced nbdev functionality. Also see our _Explanations_ in the sidebar on the left for deep-dives on specific topics."
+    "Read on to learn about more advanced nbdev functionality. Also see our [explanations](/explanations) for deep-dives on specific topics, as well as our other [tutorials](/tutorials)."
    ]
   },
   {
@@ -1531,6 +1550,13 @@
    "display_name": "python3",
    "language": "python",
    "name": "python3"
+  },
+  "widgets": {
+   "application/vnd.jupyter.widget-state+json": {
+    "state": {},
+    "version_major": 2,
+    "version_minor": 0
+   }
   }
  },
  "nbformat": 4,