tutorial

Author: jph00

nbs/tutorial.ipynb

@@ -166,7 +166,7 @@
    "source": [
     "Jupyter Notebooks can cause challenges with git conflicts, but life becomes much easier when you use `nbdev`. As a first step, run `nbdev_install_hooks` in the terminal from your project folder. This will set up hooks which will remove metadata from your notebooks when you commit, greatly reducing the chance you have a conflict.\n",
     "\n",
-    "But if you do get a conflict later, simply run `nbdev_clean filename.ipynb`. This will replace any conflicts in cell outputs with your version, and if there are conflicts in input cells, then both cells will be included in the merged file, along with standard conflict markers (e.g. `=====`). Then you can open the notebook in Jupyter and choose which version to keep."
+    "But if you do get a conflict later, simply run `nbdev_fix filename.ipynb`. This will replace any conflicts in cell outputs with your version, and if there are conflicts in input cells, then both cells will be included in the merged file, along with standard conflict markers (e.g. `=====`). Then you can open the notebook in Jupyter and choose which version to keep."
    ]
   },
   {
@@ -350,37 +350,32 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Edit index.ipynb"
+    "## Build and install lib"
    ]
   },
   {
    "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*. So click on that to open it now.\n",
+    "Now you can create your Python module. To do so, just run `nbdev_export` from the terminal at the root of your project folder, which builds the .py modules and library from the jupyter notebook.\n",
     "\n",
-    "You'll see that there's already a line there to import your library - change it to use the name you selected in `settings.ini`. Then, add information about how to use your module, including some examples. Remember, these examples should be actual notebook code cells with real outputs."
+    "Before you continue, you should ensure you have the latest version of your Python library and Quarto installed.  Run `nbdev_install` to do an [editable install](https://stackoverflow.com/questions/35064426/when-would-the-e-editable-option-be-useful-with-pip-install) of your local Python library as well as fetch and install the latest version of Quarto. "
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Build lib + test"
+    "## Edit index.ipynb"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Now you can create your Python module. To do so, just run `nbdev_prepare` from the terminal at the root of your project folder. `nbdev_prepare` bundles the following commands together for you to test your code and build the library.  While running `nbdev_prepare` is convenient, you have the flexibility to choose these separate pieces.\n",
-    "\n",
-    "- `nbdev_export`: Builds the .py modules and library from the jupyter notebook\n",
-    "- `nbdev_test`: Tests all your notebooks\n",
-    "- `nbdev_clean`: Cleans your notebooks to get rid of extreanous output for Github\n",
-    "\n",
+    "Now you're ready to create your documentation home page and README.md file; these are both generated automatically from *index.ipynb*. So click on that to open it now.\n",
     "\n",
-    "Sometimes you may want to ensure you have the latest version of your Python library and Quarto installed.  You can run `nbdev_install` to do an editable install of your local Python library as well as fetch and install the latest version of Quarto. "
+    "You'll see that there's already a line there to import your library - change it to use the name you selected in `settings.ini`. Then, add information about how to use your module, including some examples. Remember, these examples should be actual notebook code cells with real outputs."
    ]
   },
   {
@@ -399,6 +394,17 @@
     "## Commit to Github"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Before commiting to GitHub we recommend running `nbdev_prepare`, which bundles the following commands together for you to test your code and build the library:\n",
+    "\n",
+    "- `nbdev_export`: Builds the .py modules and library from the jupyter notebook\n",
+    "- `nbdev_test`: Tests all your notebooks\n",
+    "- `nbdev_clean`: Cleans your notebooks to get rid of extreanous output for Github"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -432,7 +438,7 @@
     "\n",
     "#### Automatically building Docs\n",
     "\n",
-    "CI will automatically build docs and deploy them for you.  You can see the code for this in `.github/workflows/deploy.yaml`, but you normally don't have to worry about this unless you need to customize something.  There might be certain circumstances in which your organization has disabled GitHub pages by default.  If this is the case, you can enable Github Pages by clicking on the  *Settings* tab in your repo, then click *Pages* on the left side bar.  Set \"Source\" to *`gh-pages` branch and the `/root` folder*. Once you've saved, if you refresh that page, Github will have a link to your new website. Copy that URL, and then go back to your main repo page, click \"edit\" next to the description and paste the URL into the \"website\" section. While you're there, go ahead and put in your project description too. \n",
+    "CI will automatically build docs and deploy them for you.  You can see the code for this in `.github/workflows/deploy.yaml`. You can enable Github Pages by clicking on the  *Settings* tab in your repo, then click *Pages* on the left side bar.  Set \"Source\" to *`gh-pages` branch and the `/root` folder*. Once you've saved, if you refresh that page, Github will have a link to your new website. Copy that URL, and then go back to your main repo page, click \"edit\" next to the description and paste the URL into the \"website\" section. While you're there, go ahead and put in your project description too. \n",
     "\n",
     "#### Docs URL\n",
     "\n",
@@ -623,10 +629,11 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "It's helpful to be able to export all your modules directly from a notebook, rather than going to the terminal to do it. All nbdev commands are available directly from a notebook in Python. Add this line to any cell and run it to export your modules (I normally make this the last cell of my notebooks).\n",
+    "It's helpful to be able to export all your modules directly from a notebook, rather than going to the terminal to do it. All nbdev commands are available directly from a notebook in Python. A new cell with the following contents and run it to export your modules (I normally make this the last cell of my notebooks).\n",
     "\n",
     "```python\n",
-    "from nbdev.doclinks import nbdev_export\n",
+    "#| hide\n",
+    "from nbdev import nbdev_export\n",
     "nbdev_export()\n",
     "```"
    ]
@@ -635,36 +642,13 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Run tests in parallel"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "Before you push to github or make a release, you might want to run all your tests. nbdev can run all your notebooks in parallel to check for errors. Just run `nbdev_test` in a terminal.\n",
-    "\n",
     "## Code Execution & Skipping Cells\n",
     "\n",
     "If you want to prevent code from getting executed when rendering or testing docs, use the comment `|#eval: false` in a code cell.  \n",
     "\n",
     "See the [Quarto docs](https://quarto.org/docs/computations/execution-options.html) for more execution options."
    ]
   },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## View docs locally"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "If you want to look at your docs locally before you push to Github, you can do so by running `nbdev_preview`."
-   ]
-  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -711,24 +695,6 @@
     "```"
    ]
   },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Test with editable install"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "To test and use your modules in other projects, and use your console scripts (if you have any), the easiest approach is to use an [editable install](http://codumentary.blogspot.com/2014/11/python-tip-of-year-pip-install-editable.html). To do this, `cd` to the root of your repo in the terminal, and type:\n",
-    "```\n",
-    "pip install -e .\n",
-    "```\n",
-    "(Note that the trailing period is important.) Your module changes will be automatically picked up without reinstalling. If you add any additional console scripts, you will need to run this command again.  After doing an editable install you can run `nbdev_test` to run all of the tests in your notebooks."
-   ]
-  },
   {
    "cell_type": "markdown",
    "metadata": {},