{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# nbdev1 migration\n",
    "\n",
    "> How to change your nbdev1 repo to work with nbdev2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "nbdev v2 is a new from-scratch rewrite of nbdev that's not backwards compatible. This page describes the changes you need to make to upgrade your nbdev v1 repo to work with the new version. The steps shown here should work on macOS or Linux (including Windows WSL)\n",
    "\n",
    "The biggest change is that nbdev2 uses [Quarto](https://quarto.org/) to generate your website, whereas nbdev1 used nbconvert and jekyll. You can use all of Quarto's features directly in nbdev, so checkout the Quarto website to see all the amazing functionality it supports."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Initial setup"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you've pinned nbdev in `requirements.txt` or `settings.ini` (e.g `nbdev<2`) remove the version pin. (*If you don't know what this means, then you don't have it, so you can ignore this step*).\n",
    "\n",
    "Install the latest version of nbdev by typing:\n",
    "\n",
    "    pip install -U nbdev\n",
    "\n",
    "or:\n",
    "\n",
    "    conda install -c fastai nbdev\n",
    "\n",
    "You may need to restart your terminal for the new commands to be visible to your shell."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Upgrade directives"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "nbdev has slightly changed how \"directive comments\" like `export` and `default_exp` work, in order to align with how Quarto does things. Now, instead of just adding a `#` to the start to indicate a directive (e.g `#export`), you now need to use `#|` (e.g `#|export`). You can also optionally add a space (e.g `#| export`).\n",
    "\n",
    "To automatically upgrade your directives to the new format, run in the root of your repo:\n",
    "\n",
    "    nbdev_migrate\n",
    "\n",
    "You should now test that you can export your module by running:\n",
    "\n",
    "    nbdev_export\n",
    "\n",
    "Note that `nbdev_export` replaces `nbdev_build_lib`. Run `nbdev_export -h` to see the options you can pass to it (normally you won't need to pass any). To see a list of all the commands available in nbdev2, run `nbdev_help`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Add and remove files"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "First set a variable with the name of your library, by running the following (replacing \"yourlib\" with the name of your library's subdirectory)\n",
    "\n",
    "    export LIBNAME=yourlib\n",
    "\n",
    "Now run the following:\n",
    "\n",
    "```bash\n",
    "git rm Makefile\n",
    "git add $LIBNAME/_modidx.py\n",
    "rm -rf docs\n",
    "rm -f .gitconfig \n",
    "rm -f .git/hooks/post-merge\n",
    "\n",
    "rm -f setup.py\n",
    "curl -O https://raw.githubusercontent.com/fastai/nbdev-template/master/styles.css\n",
    "curl -O https://raw.githubusercontent.com/fastai/nbdev-template/master/setup.py\n",
    "\n",
    "cat >>.gitignore <<EOF\n",
    "_docs/\n",
    "sidebar.yml\n",
    "EOF\n",
    "```\n",
    "\n",
    "As you see above, we've remove the Makefile -- that's because all the things done by `make` before are now handled by `nbdev` commands directly."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    ":::{.callout-note}\n",
    "All documentation related files should be included in your `nbs_path`, and all paths should be relative to it. If you have set the `nbs_path` in your `settings.ini` file, then copy your `styles.css` file inside of your `nbs_path` folder.\n",
    ":::"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you use GitHub Actions for continuous integration (CI) you can update this to use nbdev too as follows:\n",
    "\n",
    "```bash\n",
    "curl -O https://raw.githubusercontent.com/fastai/nbdev-template/master/.github/workflows/test.yaml\n",
    "mv test.yaml .github/workflows/\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Update directive names"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A number of directives have changed names. We'll use `perl` to fix them. Run these lines in the root of your repo:\n",
    "\n",
    "```bash\n",
    "[[ $SHELL = *bash ]] && shopt -s globstar\n",
    "\n",
    "perl -pi -e 's/#\\|\\s*hide_input/#| echo: false/' **/*.ipynb\n",
    "perl -pi -e 's/#\\|\\s*hide_output/#| output: false/' **/*.ipynb\n",
    "perl -pi -e 's/#\\|\\s*skip/#| eval: false/' **/*.ipynb\n",
    "perl -pi -e 's/from nbdev.export import notebook2script/from nbdev import nbdev_export/' **/*.ipynb\n",
    "perl -pi -e 's/notebook2script/nbdev_export/' **/*.ipynb\n",
    "```\n",
    "\n",
    "These change the following directives to use functionality built into Quarto:\n",
    "\n",
    "- `hide_input` --> `echo: false`\n",
    "- `hide_output` --> `output: false`\n",
    "- `skip` --> `eval: false`\n",
    "\n",
    "They also update the new location and name of the `nbdev_export` python function.\n",
    "\n",
    "If you have any notebooks that you've asked nbdev1 to skip (using `all_slow`), you'll need to add a [raw cell](https://quarto.org/docs/tools/jupyter-lab.html#yaml-front-matter) to the top of your notebook containing YAML frontmatter. The frontmatter needs to include `skip_showdoc: true` to avoid running cells when rendering docs, and `skip_exec: true` to skip this notebook when running tests. E.g to do both, you would add a raw cell (or update your existing frontmatter raw cell) to contain:\n",
    "\n",
    "```\n",
    "---\n",
    "skip_showdoc: true\n",
    "skip_exec: true\n",
    "---\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Final steps"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You should now edit `settings.ini`, and change `doc_path` from `docs` to `_docs`, since that's where nbdev2 will build your website.\n",
    "\n",
    "If you use a custom domain for your website, you should move your `CNAME` file into the directory containing your notebooks.\n",
    "\n",
    "Before pushing to GitHub, check that your website looks OK locally by running:\n",
    "\n",
    "    nbdev_preview\n",
    "\n",
    "Now prepare to commit to GitHub:\n",
    "\n",
    "    nbdev_prepare\n",
    "\n",
    "You can now commit to GitHub as usual. Finally, update 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."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}