{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Getting started\n",
    "\n",
    "> Create delightful software with Jupyter Notebooks"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`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!  See the [Getting Started](#Getting-Started) section below for more."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Install"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "With pip:\n",
    "\n",
    "    pip install nbdev\n",
    "\n",
    "With conda:\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": [
    "## Getting started"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We suggest these helpful resources to get started with `nbdev`:\n",
    "\n",
    "- [Official tutorial](https://nbdev.fast.ai/tutorial.html);  (we suggest replicating each step to solidify your understanding)\n",
    "- [Official documentation](https://nbdev.fast.ai/getting_started.html)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "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_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 git hooks to clean and trust notebooks automatically\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_migrate_directives\u001b[0m        Convert all directives 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_release\u001b[0m                   Release both conda and PyPI packages\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": [
    "!nbdev_help"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## FAQ"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Q: Someone told me not to use notebooks for \"serious\" software development!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[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": [
    "## nbdev in the wild"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### fastai ecosystem"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`nbdev` has been used to build innovative software in the fastai ecosystem, including the [`fastai`](https://docs.fast.ai/) deep learning library which implements a [unique layered API and callback system](https://arxiv.org/abs/2002.04688), and [`fastcore`](https://fastcore.fast.ai/), which supercharges Python leveraging its dynamic nature. Furthermore, `nbdev` allows a very small number of developers to maintain and grow a [large ecosystem](https://github.com/fastai) of software engineering, data science, machine learning, and devops tools."
   ]
  },
  {
   "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_git_hooks` in the cloned repository."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Copyright"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Copyright 2019 onwards, 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
}