nbs/getting_started.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Getting started\n",
    "\n",
    "> Create delightful software with Jupyter Notebooks"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "::: {.content-visible when-format=\"markdown\"}\n",
    "\n",
    "![CI](https://github.com/fastai/nbdev/actions/workflows/test.yaml/badge.svg)\n",
    "\n",
    ":::"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*NB: This is nbdev v2, a major upgrade of nbdev. Whilst the differences to nbdev1 aren't huge, it does require some changes. The old version docs are at [nbdev1.fast.ai](https://nbdev1.fast.ai). You can use version-pinning in `settings.ini` (i.e `'nbdev<2'`) to stop nbdev from upgrading. To upgrade, follow the [migration tutorial](https://nbdev.fast.ai/migrating.html).*\n",
    "\n",
    "---\n",
    "\n",
    "`nbdev` is a system for *exploratory programming*.  Simply write notebooks with lightweight markup and get high-quality documentation, tests, continuous integration, and packaging for free!\n",
    "\n",
    "`nbdev` makes debugging and refactoring your code much easier than in traditional programming environments since you always have live objects at your fingertips.  `nbdev` also promotes software engineering best practices because tests and documentation are first class."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- **Documentation** is automatically generated using [Quarto](https://quarto.org/) and hosted on [GitHub Pages](https://pages.github.com/).  Docs support LaTeX, are searchable, and are automatically hyperlinked (including out-of-the-box support for many packages via [`nbdev-index`](https://github.com/fastai/nbdev-index)).  You also have fine-grained control over how cells are displayed.\n",
    "- **Publish packages to PyPI and conda** as well as tools to simplify package releases.  Python best practices are automatically followed, for example, only exported objects are included in `__all__`\n",
    "- **Two-way sync between notebooks and plaintext** source code allowing you to use your IDE for code navigation or quick edits.\n",
    "- **Tests** written as ordinary notebook cells are run in parallel with a single command.  You have fine-grained control over which tests are run.\n",
    "- **Continuous integration** out-of-the-box with [GitHub Actions](https://github.com/features/actions) that run your tests on each push and rebuild docs on each merge.\n",
    "- **Git-friendly notebooks** with tools that clean unwanted metadata and render merge conflicts in a human-readable format.\n",
    "- ... and much more!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Install"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "nbdev works on macOS, Linux, and most Unix-style operating systems. It works on Windows under WSL, but not under cmd or Powershell.\n",
    "\n",
    "You can install nbdev with pip:\n",
    "\n",
    "    pip install nbdev\n",
    "\n",
    "... or with conda (or mamba):\n",
    "\n",
    "    conda install -c fastai nbdev\n",
    "\n",
    "Note that `nbdev` must be installed into the same Python environment that you use for both Jupyter and your project."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## How to use nbdev"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The best way to learn to use nbdev is to complete one of these tutorials (we suggest replicating each step to solidify your understanding):\n",
    "\n",
    "- [Written tutorial](https://nbdev.fast.ai/tutorial.html)\n",
    "\n",
    "**Video step-by-step walkthru** (to view full screen, click the little square in the bottom right of the video; to view in a separate Youtube window, click the Youtube logo):"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "::: {.content-visible when-format=\"html\"}\n",
    "\n",
    "<iframe width=\"560\" height=\"315\" src=\"https://www.youtube-nocookie.com/embed/l7zS8Ld4_iA\" frameborder=\"0\" allow=\"accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture\" allowfullscreen></iframe>\n",
    "\n",
    ":::"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "::: {.content-visible when-format=\"markdown\"}\n",
    "\n",
    "[![](https://github.com/fastai/logos/raw/main/nbdev_walkthrough.png)](http://www.youtube.com/watch?v=l7zS8Ld4_iA \"nbdev walkthrough\"){target=\"_blank\"}\n",
    "\n",
    ":::"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(There's an [alternate version of the walkthru](https://youtu.be/67FdzLSt4aA) available with the coding sections sped up using the `unsilence` python library -- it's 27 minutes faster, but it's be harder to follow along with.)\n",
    "\n",
    "You can run `nbdev_help` from the terminal to see the full list of available commands:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\u001b[1m\u001b[94mnbdev_bump_version\u001b[0m              Increment version in settings.ini by one\n",
      "\u001b[1m\u001b[94mnbdev_changelog\u001b[0m                 Create a CHANGELOG.md file from closed and labeled GitHub issues\n",
      "\u001b[1m\u001b[94mnbdev_clean\u001b[0m                     Clean all notebooks in `fname` to avoid merge conflicts\n",
      "\u001b[1m\u001b[94mnbdev_conda\u001b[0m                     Create and upload a conda package\n",
      "\u001b[1m\u001b[94mnbdev_create_config\u001b[0m             Create a config file\n",
      "\u001b[1m\u001b[94mnbdev_deploy\u001b[0m                    Deploy docs to GitHub Pages\n",
      "\u001b[1m\u001b[94mnbdev_docs\u001b[0m                      Generate docs\n",
      "\u001b[1m\u001b[94mnbdev_export\u001b[0m                    Export notebooks in `path` to Python modules\n",
      "\u001b[1m\u001b[94mnbdev_filter\u001b[0m                    A notebook filter for Quarto\n",
      "\u001b[1m\u001b[94mnbdev_fix\u001b[0m                       Create working notebook from conflicted notebook `nbname`\n",
      "\u001b[1m\u001b[94mnbdev_ghp_deploy\u001b[0m                Deploy docs in `doc_path` from settings.ini to GitHub Pages\n",
      "\u001b[1m\u001b[94mnbdev_help\u001b[0m                      Show help for all console scripts\n",
      "\u001b[1m\u001b[94mnbdev_install\u001b[0m                   Install Quarto and the current library\n",
      "\u001b[1m\u001b[94mnbdev_install_hooks\u001b[0m             Install Jupyter and git hooks to automatically clean, trust, and fix merge conflicts in notebooks\n",
      "\u001b[1m\u001b[94mnbdev_install_quarto\u001b[0m            Install latest Quarto on macOS or Linux, prints instructions for Windows\n",
      "\u001b[1m\u001b[94mnbdev_merge\u001b[0m                     Git merge driver for notebooks\n",
      "\u001b[1m\u001b[94mnbdev_migrate\u001b[0m                   Convert all directives and callouts in `fname` from v1 to v2\n",
      "\u001b[1m\u001b[94mnbdev_new\u001b[0m                       Create a new project from the current git repo\n",
      "\u001b[1m\u001b[94mnbdev_prepare\u001b[0m                   Export, test, and clean notebooks\n",
      "\u001b[1m\u001b[94mnbdev_preview\u001b[0m                   Start a local docs webserver\n",
      "\u001b[1m\u001b[94mnbdev_pypi\u001b[0m                      Create and upload Python package to PyPI\n",
      "\u001b[1m\u001b[94mnbdev_quarto\u001b[0m                    Create Quarto docs and README.md\n",
      "\u001b[1m\u001b[94mnbdev_readme\u001b[0m                    Render README.md from index.ipynb\n",
      "\u001b[1m\u001b[94mnbdev_release\u001b[0m                   Release both conda and PyPI packages\n",
      "\u001b[1m\u001b[94mnbdev_release_gh\u001b[0m                Calls `nbdev_changelog`, lets you edit the result, then pushes to git and calls `nbdev_release_git`\n",
      "\u001b[1m\u001b[94mnbdev_release_git\u001b[0m               Tag and create a release in GitHub for the current version\n",
      "\u001b[1m\u001b[94mnbdev_sidebar\u001b[0m                   Create sidebar.yml\n",
      "\u001b[1m\u001b[94mnbdev_test\u001b[0m                      Test in parallel notebooks matching `fname`, passing along `flags`\n",
      "\u001b[1m\u001b[94mnbdev_trust\u001b[0m                     Trust notebooks matching `fname`\n",
      "\u001b[1m\u001b[94mnbdev_update\u001b[0m                    Propagate change in modules matching `fname` to notebooks that created them\n"
     ]
    }
   ],
   "source": [
    "#| exec_doc\n",
    "!nbdev_help"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Installing Quarto"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that when you setup your first project, nbdev will attempt to automatically download and install [quarto](https://quarto.org/) for you. This is the program that we use to create your documentation website.\n",
    "\n",
    "Quarto's standard installation process requires root access, and nbdev will therefore ask for your root password during installation. For most people, this will work fine and everything will be handled automatically -- if so, you can skip over the rest of this section, which talks about installing without root access.\n",
    "\n",
    "If you need to install quarto without root access on Linux, first `cd` to wherever you want to store it, then [download quarto](https://quarto.org/docs/get-started/), and type:\n",
    "\n",
    "```bash\n",
    "dpkg -x quarto*.deb .\n",
    "mv opt/quarto ./\n",
    "rmdir opt\n",
    "mkdir -p ~/.local/bin\n",
    "ln -s \"$(pwd)\"/quarto/bin/quarto ~/.local/bin\n",
    "```\n",
    "\n",
    "To use this non-root version of quarto, you'll need `~/.local/bin` in your [`PATH` environment variable](https://linuxize.com/post/how-to-add-directory-to-path-in-linux/). (Alternatively, change the `ln -s` step to place the symlink somewhere else in your path.)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## FAQ"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Q: What is the warning \"Found a cell containing mix of imports and computations. Please use separate cells\"?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A: You should not have cells that are not exported, *and* contain a mix of `import` statements along with other code. For instance, don't do this in a single cell:\n",
    "\n",
    "```python\n",
    "import some_module\n",
    "some_module.something()\n",
    "```\n",
    "\n",
    "Instead, split this into two cells, one which does `import some_module`, and the other which does `some_module.something()`.\n",
    "\n",
    "The reason for this is that when we create your documentation website, we ensure that all of the signatures for functions you document are up to date, by running the imports, exported cells, and `show_doc` functions in your notebooks. When you mix imports with other code, that other code will be run too, which can cause errors (or at least slowdowns) when creating your website."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Q: Someone told me not to use notebooks for \"serious\" software development!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A: [Watch this video](https://youtu.be/9Q6sLbz37gk).  Don't worry, we still get this too, despite having used `nbdev` for a wide range of \"very serious\" software projects over the last three years, including [deep learning libraries](https://github.com/fastai/fastai), [API clients](https://github.com/fastai/ghapi), [Python language extensions](https://github.com/fastai/fastcore), [terminal user interfaces](https://github.com/nat/ghtop), and more!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Contributing"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you want to contribute to `nbdev`, be sure to review the [contributions guidelines](https://github.com/fastai/nbdev/blob/master/CONTRIBUTING.md). This project adheres to fastai's [code of conduct](https://github.com/fastai/nbdev/blob/master/CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. In general, we strive to abide by generally accepted best practices in open-source software development.\n",
    "\n",
    "Make sure you have `nbdev`'s git hooks installed by running `nbdev_install_hooks` in the cloned repository."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Copyright"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Copyright © 2019 onward fast.ai, Inc. Licensed under the Apache License, Version 2.0 (the \"License\"); you may not use this project's files except in compliance with the License. A copy of the License is provided in the LICENSE file in this repository."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}