|
| 1 | +{ |
| 2 | + "cells": [ |
| 3 | + { |
| 4 | + "cell_type": "markdown", |
| 5 | + "metadata": {}, |
| 6 | + "source": [ |
| 7 | + "# About nbdev\n", |
| 8 | + "\n", |
| 9 | + "> Create delightful Python projects using exploratory programming" |
| 10 | + ] |
| 11 | + }, |
| 12 | + { |
| 13 | + "cell_type": "markdown", |
| 14 | + "metadata": {}, |
| 15 | + "source": [ |
| 16 | + "`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", |
| 17 | + "\n", |
| 18 | + "`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." |
| 19 | + ] |
| 20 | + }, |
| 21 | + { |
| 22 | + "cell_type": "markdown", |
| 23 | + "metadata": {}, |
| 24 | + "source": [ |
| 25 | + "- **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", |
| 26 | + "- **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", |
| 27 | + "- **Two-way sync between notebooks and plaintext** source code allowing you to use your IDE for code navigation or quick edits.\n", |
| 28 | + "- **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", |
| 29 | + "- **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", |
| 30 | + "- **Git-friendly notebooks** with tools that clean unwanted metadata and render merge conflicts in a human-readable format.\n", |
| 31 | + "- ... and much more! See the [Getting Started](#Getting-Started) section below for more." |
| 32 | + ] |
| 33 | + }, |
| 34 | + { |
| 35 | + "cell_type": "markdown", |
| 36 | + "metadata": {}, |
| 37 | + "source": [ |
| 38 | + "## Install" |
| 39 | + ] |
| 40 | + }, |
| 41 | + { |
| 42 | + "cell_type": "markdown", |
| 43 | + "metadata": {}, |
| 44 | + "source": [ |
| 45 | + "With pip:\n", |
| 46 | + "\n", |
| 47 | + " pip install nbdev\n", |
| 48 | + "\n", |
| 49 | + "With conda:\n", |
| 50 | + "\n", |
| 51 | + " conda install -c fastai nbdev\n", |
| 52 | + "\n", |
| 53 | + "Note that `nbdev` must be installed into the same Python environment that you use for both Jupyter and your project." |
| 54 | + ] |
| 55 | + }, |
| 56 | + { |
| 57 | + "cell_type": "markdown", |
| 58 | + "metadata": {}, |
| 59 | + "source": [ |
| 60 | + "## Getting started" |
| 61 | + ] |
| 62 | + }, |
| 63 | + { |
| 64 | + "cell_type": "markdown", |
| 65 | + "metadata": {}, |
| 66 | + "source": [ |
| 67 | + "We suggest these helpful resources to get started with `nbdev`:\n", |
| 68 | + "\n", |
| 69 | + "- [Official tutorial](https://nbdev.fast.ai/tutorial.html); (we suggest replicating each step to solidify your understanding)\n", |
| 70 | + "- [Official documentation](https://nbdev.fast.ai/)." |
| 71 | + ] |
| 72 | + }, |
| 73 | + { |
| 74 | + "cell_type": "markdown", |
| 75 | + "metadata": {}, |
| 76 | + "source": [ |
| 77 | + "You can run `nbdev_help` from the terminal to see the full list of available commands:" |
| 78 | + ] |
| 79 | + }, |
| 80 | + { |
| 81 | + "cell_type": "code", |
| 82 | + "execution_count": null, |
| 83 | + "metadata": {}, |
| 84 | + "outputs": [ |
| 85 | + { |
| 86 | + "name": "stdout", |
| 87 | + "output_type": "stream", |
| 88 | + "text": [ |
| 89 | + "\u001b[1m\u001b[94mnbdev_bump_version\u001b[0m Increment version in settings.ini by one\n", |
| 90 | + "\u001b[1m\u001b[94mnbdev_clean\u001b[0m Clean all notebooks in `fname` to avoid merge conflicts\n", |
| 91 | + "\u001b[1m\u001b[94mnbdev_conda\u001b[0m Create and upload a conda package\n", |
| 92 | + "\u001b[1m\u001b[94mnbdev_create_config\u001b[0m Create a config file\n", |
| 93 | + "\u001b[1m\u001b[94mnbdev_deploy\u001b[0m Deploy docs to GitHub Pages\n", |
| 94 | + "\u001b[1m\u001b[94mnbdev_docs\u001b[0m Generate docs\n", |
| 95 | + "\u001b[1m\u001b[94mnbdev_export\u001b[0m Export notebooks in `path` to Python modules\n", |
| 96 | + "\u001b[1m\u001b[94mnbdev_filter\u001b[0m A notebook filter for Quarto\n", |
| 97 | + "\u001b[1m\u001b[94mnbdev_fix\u001b[0m Create working notebook from conflicted notebook `nbname`\n", |
| 98 | + "\u001b[1m\u001b[94mnbdev_ghp_deploy\u001b[0m Deploy docs in `doc_path` from settings.ini to GitHub Pages\n", |
| 99 | + "\u001b[1m\u001b[94mnbdev_help\u001b[0m Show help for all console scripts\n", |
| 100 | + "\u001b[1m\u001b[94mnbdev_install\u001b[0m Install Quarto and the current library\n", |
| 101 | + "\u001b[1m\u001b[94mnbdev_install_hooks\u001b[0m Install git hooks to clean and trust notebooks automatically\n", |
| 102 | + "\u001b[1m\u001b[94mnbdev_install_quarto\u001b[0m Install latest Quarto on macOS or Linux, prints instructions for Windows\n", |
| 103 | + "\u001b[1m\u001b[94mnbdev_migrate_directives\u001b[0m Convert all directives in `fname` from v1 to v2\n", |
| 104 | + "\u001b[1m\u001b[94mnbdev_new\u001b[0m Create a new project from the current git repo\n", |
| 105 | + "\u001b[1m\u001b[94mnbdev_prepare\u001b[0m Export, test, and clean notebooks\n", |
| 106 | + "\u001b[1m\u001b[94mnbdev_preview\u001b[0m Start a local docs webserver\n", |
| 107 | + "\u001b[1m\u001b[94mnbdev_pypi\u001b[0m Create and upload Python package to PyPI\n", |
| 108 | + "\u001b[1m\u001b[94mnbdev_quarto\u001b[0m Create Quarto docs and README.md\n", |
| 109 | + "\u001b[1m\u001b[94mnbdev_release\u001b[0m Release both conda and PyPI packages\n", |
| 110 | + "\u001b[1m\u001b[94mnbdev_sidebar\u001b[0m Create sidebar.yml\n", |
| 111 | + "\u001b[1m\u001b[94mnbdev_test\u001b[0m Test in parallel notebooks matching `fname`, passing along `flags`\n", |
| 112 | + "\u001b[1m\u001b[94mnbdev_trust\u001b[0m Trust notebooks matching `fname`\n", |
| 113 | + "\u001b[1m\u001b[94mnbdev_update\u001b[0m Propagate change in modules matching `fname` to notebooks that created them\n" |
| 114 | + ] |
| 115 | + } |
| 116 | + ], |
| 117 | + "source": [ |
| 118 | + "!nbdev_help" |
| 119 | + ] |
| 120 | + }, |
| 121 | + { |
| 122 | + "cell_type": "markdown", |
| 123 | + "metadata": {}, |
| 124 | + "source": [ |
| 125 | + "## FAQ" |
| 126 | + ] |
| 127 | + }, |
| 128 | + { |
| 129 | + "cell_type": "markdown", |
| 130 | + "metadata": {}, |
| 131 | + "source": [ |
| 132 | + "### Q: Someone told me not to use notebooks for \"serious\" software development!" |
| 133 | + ] |
| 134 | + }, |
| 135 | + { |
| 136 | + "cell_type": "markdown", |
| 137 | + "metadata": {}, |
| 138 | + "source": [ |
| 139 | + "[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!" |
| 140 | + ] |
| 141 | + }, |
| 142 | + { |
| 143 | + "cell_type": "markdown", |
| 144 | + "metadata": {}, |
| 145 | + "source": [ |
| 146 | + "## nbdev in the wild" |
| 147 | + ] |
| 148 | + }, |
| 149 | + { |
| 150 | + "cell_type": "markdown", |
| 151 | + "metadata": {}, |
| 152 | + "source": [ |
| 153 | + "### fastai ecosystem" |
| 154 | + ] |
| 155 | + }, |
| 156 | + { |
| 157 | + "cell_type": "markdown", |
| 158 | + "metadata": {}, |
| 159 | + "source": [ |
| 160 | + "`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." |
| 161 | + ] |
| 162 | + }, |
| 163 | + { |
| 164 | + "cell_type": "markdown", |
| 165 | + "metadata": {}, |
| 166 | + "source": [ |
| 167 | + "## Contributing" |
| 168 | + ] |
| 169 | + }, |
| 170 | + { |
| 171 | + "cell_type": "markdown", |
| 172 | + "metadata": {}, |
| 173 | + "source": [ |
| 174 | + "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", |
| 175 | + "\n", |
| 176 | + "Make sure you have `nbdev`'s git hooks installed by running `nbdev_install_git_hooks` in the cloned repository." |
| 177 | + ] |
| 178 | + }, |
| 179 | + { |
| 180 | + "cell_type": "markdown", |
| 181 | + "metadata": {}, |
| 182 | + "source": [ |
| 183 | + "## Copyright" |
| 184 | + ] |
| 185 | + }, |
| 186 | + { |
| 187 | + "cell_type": "markdown", |
| 188 | + "metadata": {}, |
| 189 | + "source": [ |
| 190 | + "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." |
| 191 | + ] |
| 192 | + } |
| 193 | + ], |
| 194 | + "metadata": { |
| 195 | + "kernelspec": { |
| 196 | + "display_name": "Python 3 (ipykernel)", |
| 197 | + "language": "python", |
| 198 | + "name": "python3" |
| 199 | + } |
| 200 | + }, |
| 201 | + "nbformat": 4, |
| 202 | + "nbformat_minor": 4 |
| 203 | +} |
0 commit comments