# Getting Started
<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
*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).*
------------------------------------------------------------------------
`nbdev` is a notebook-driven development platform. Simply write
notebooks with lightweight markup and get high-quality documentation,
tests, continuous integration, and packaging for free!
`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.
- **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))
- **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__`
- **Two-way sync between notebooks and plaintext source code** allowing
you to use your IDE for code navigation or quick edits
- **Tests** written as ordinary notebook cells are run in parallel with
a single command
- **Continuous integration** out-of-the-box with [GitHub
Actions](https://github.com/features/actions) that run your tests and
rebuild your docs
- **Git-friendly notebooks** with [Jupyter/Git
hooks](https://nbdev.fast.ai/tutorials/git_friendly_jupyter.html) that
clean unwanted metadata and render merge conflicts in a human-readable
format
- … and much more!
## Install
nbdev works on macOS, Linux, and most Unix-style operating systems. It
works on Windows under WSL, but not under cmd or Powershell.
You can install nbdev with pip:
``` sh
pip install nbdev
```
… or with conda (or mamba):
``` sh
conda install -c fastai nbdev
```
Note that `nbdev` must be installed into the same Python environment
that you use for both Jupyter and your project.
## How to use nbdev
The best way to learn how to use nbdev is to complete either the
[written walkthrough](https://nbdev.fast.ai/tutorials/tutorial.html) or
video walkthrough:
<div>
<a href="http://www.youtube.com/watch?v=l7zS8Ld4_iA" target="_blank"
title="nbdev walkthrough"><img
src="https://github.com/fastai/logos/raw/main/nbdev_walkthrough.png"
style="border-radius: 10px" width="560" height="315" /></a>
</div>
Alternatively, there’s a [shortened version of the video
walkthrough](https://youtu.be/67FdzLSt4aA) with coding sections sped up
using the `unsilence` Python library – it’s 27 minutes faster, but a bit
harder to follow.
You can also run `nbdev_help` from the terminal to see the full list of
available commands:
``` python
!nbdev_help
```
nbdev_bump_version Increment version in settings.ini by one
nbdev_changelog Create a CHANGELOG.md file from closed and labeled GitHub issues
nbdev_clean Clean all notebooks in `fname` to avoid merge conflicts
nbdev_conda Create a `meta.yaml` file ready to be built into a package, and optionally build and upload it
nbdev_create_config Create a config file.
nbdev_deploy Deploy docs to GitHub Pages
nbdev_docs Create Quarto docs and README.md
nbdev_export Export notebooks in `path` to Python modules
nbdev_filter A notebook filter for Quarto
nbdev_fix Create working notebook from conflicted notebook `nbname`
nbdev_help Show help for all console scripts
nbdev_install Install Quarto and the current library
nbdev_install_hooks Install Jupyter and git hooks to automatically clean, trust, and fix merge conflicts in notebooks
nbdev_install_quarto Install latest Quarto on macOS or Linux, prints instructions for Windows
nbdev_merge Git merge driver for notebooks
nbdev_migrate Convert all directives and callouts in `fname` from v1 to v2
nbdev_new Create an nbdev project.
nbdev_prepare Export, test, and clean notebooks, and render README if needed
nbdev_preview Preview docs locally
nbdev_proc_nbs Process notebooks in `path` for docs rendering
nbdev_pypi Create and upload Python package to PyPI
nbdev_readme None
nbdev_release_both Release both conda and PyPI packages
nbdev_release_gh Calls `nbdev_changelog`, lets you edit the result, then pushes to git and calls `nbdev_release_git`
nbdev_release_git Tag and create a release in GitHub for the current version
nbdev_sidebar Create sidebar.yml
nbdev_test Test in parallel notebooks matching `path`, passing along `flags`
nbdev_trust Trust notebooks matching `fname`
nbdev_update Propagate change in modules matching `fname` to notebooks that created them
## FAQ
### Q: What is the warning “Found a cell containing mix of imports and computations. Please use separate cells”?
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:
``` python
import some_module
some_module.something()
```
Instead, split this into two cells, one which does `import some_module`,
and the other which does `some_module.something()`.
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`](https://nbdev.fast.ai/api/showdoc.html#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.
### Q: Why is nbdev asking for root access? How do I install Quarto without root access?
A: 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.
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.
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:
``` bash
dpkg -x quarto*.deb .
mv opt/quarto ./
rmdir opt
mkdir -p ~/.local/bin
ln -s "$(pwd)"/quarto/bin/quarto ~/.local/bin
```
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.)
### Q: Someone told me not to use notebooks for “serious” software development!
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!
## Contributing
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.
Make sure you have `nbdev`’s git hooks installed by running
[`nbdev_install_hooks`](https://nbdev.fast.ai/api/clean.html#nbdev_install_hooks)
in the cloned repository.
## Copyright
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.
Raw data
{
"_id": null,
"home_page": "https://github.com/fastai/nbdev",
"name": "nbdev",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "nbdev fastai jupyter notebook export",
"author": "Jeremy Howard and Hamel Husain",
"author_email": "j@fast.ai",
"download_url": "https://files.pythonhosted.org/packages/2a/fc/dbed3cce46a63df21ba718e526896e97f5eeb64886ccd85059b352fb8c4e/nbdev-2.3.13.tar.gz",
"platform": null,
"description": "# Getting Started\n\n<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->\n\n\n\n*NB: This is nbdev v2, a major upgrade of nbdev. Whilst the differences\nto nbdev1 aren\u2019t huge, it does require some changes. The old version\ndocs are at [nbdev1.fast.ai](https://nbdev1.fast.ai). You can use\nversion-pinning in `settings.ini` (i.e `'nbdev<2'`) to stop nbdev from\nupgrading. To upgrade, follow the [migration\ntutorial](https://nbdev.fast.ai/migrating.html).*\n\n------------------------------------------------------------------------\n\n`nbdev` is a notebook-driven development platform. Simply write\nnotebooks with lightweight markup and get high-quality documentation,\ntests, continuous integration, and packaging for free!\n\n`nbdev` makes debugging and refactoring your code much easier than in\ntraditional programming environments since you always have live objects\nat your fingertips. `nbdev` also promotes software engineering best\npractices because tests and documentation are first class.\n\n- **Documentation** is automatically generated using\n [Quarto](https://quarto.org/) and hosted on [GitHub\n Pages](https://pages.github.com/). Docs support LaTeX, are searchable,\n and are automatically hyperlinked (including out-of-the-box support\n for many packages via\n [`nbdev-index`](https://github.com/fastai/nbdev-index))\n- **Publish packages to PyPI and conda** as well as tools to simplify\n package releases. Python best practices are automatically followed,\n for example, only exported objects are included in `__all__`\n- **Two-way sync between notebooks and plaintext source code** allowing\n you to use your IDE for code navigation or quick edits\n- **Tests** written as ordinary notebook cells are run in parallel with\n a single command\n- **Continuous integration** out-of-the-box with [GitHub\n Actions](https://github.com/features/actions) that run your tests and\n rebuild your docs\n- **Git-friendly notebooks** with [Jupyter/Git\n hooks](https://nbdev.fast.ai/tutorials/git_friendly_jupyter.html) that\n clean unwanted metadata and render merge conflicts in a human-readable\n format\n- \u2026 and much more!\n\n## Install\n\nnbdev works on macOS, Linux, and most Unix-style operating systems. It\nworks on Windows under WSL, but not under cmd or Powershell.\n\nYou can install nbdev with pip:\n\n``` sh\npip install nbdev\n```\n\n\u2026 or with conda (or mamba):\n\n``` sh\nconda install -c fastai nbdev\n```\n\nNote that `nbdev` must be installed into the same Python environment\nthat you use for both Jupyter and your project.\n\n## How to use nbdev\n\nThe best way to learn how to use nbdev is to complete either the\n[written walkthrough](https://nbdev.fast.ai/tutorials/tutorial.html) or\nvideo walkthrough:\n\n<div>\n\n<a href=\"http://www.youtube.com/watch?v=l7zS8Ld4_iA\" target=\"_blank\"\ntitle=\"nbdev walkthrough\"><img\nsrc=\"https://github.com/fastai/logos/raw/main/nbdev_walkthrough.png\"\nstyle=\"border-radius: 10px\" width=\"560\" height=\"315\" /></a>\n\n</div>\n\nAlternatively, there\u2019s a [shortened version of the video\nwalkthrough](https://youtu.be/67FdzLSt4aA) with coding sections sped up\nusing the `unsilence` Python library \u2013 it\u2019s 27 minutes faster, but a bit\nharder to follow.\n\nYou can also run `nbdev_help` from the terminal to see the full list of\navailable commands:\n\n``` python\n!nbdev_help\n```\n\n nbdev_bump_version Increment version in settings.ini by one\n nbdev_changelog Create a CHANGELOG.md file from closed and labeled GitHub issues\n nbdev_clean Clean all notebooks in `fname` to avoid merge conflicts\n nbdev_conda Create a `meta.yaml` file ready to be built into a package, and optionally build and upload it\n nbdev_create_config Create a config file.\n nbdev_deploy Deploy docs to GitHub Pages\n nbdev_docs Create Quarto docs and README.md\n nbdev_export Export notebooks in `path` to Python modules\n nbdev_filter A notebook filter for Quarto\n nbdev_fix Create working notebook from conflicted notebook `nbname`\n nbdev_help Show help for all console scripts\n nbdev_install Install Quarto and the current library\n nbdev_install_hooks Install Jupyter and git hooks to automatically clean, trust, and fix merge conflicts in notebooks\n nbdev_install_quarto Install latest Quarto on macOS or Linux, prints instructions for Windows\n nbdev_merge Git merge driver for notebooks\n nbdev_migrate Convert all directives and callouts in `fname` from v1 to v2\n nbdev_new Create an nbdev project.\n nbdev_prepare Export, test, and clean notebooks, and render README if needed\n nbdev_preview Preview docs locally\n nbdev_proc_nbs Process notebooks in `path` for docs rendering\n nbdev_pypi Create and upload Python package to PyPI\n nbdev_readme None\n nbdev_release_both Release both conda and PyPI packages\n nbdev_release_gh Calls `nbdev_changelog`, lets you edit the result, then pushes to git and calls `nbdev_release_git`\n nbdev_release_git Tag and create a release in GitHub for the current version\n nbdev_sidebar Create sidebar.yml\n nbdev_test Test in parallel notebooks matching `path`, passing along `flags`\n nbdev_trust Trust notebooks matching `fname`\n nbdev_update Propagate change in modules matching `fname` to notebooks that created them\n\n## FAQ\n\n### Q: What is the warning \u201cFound a cell containing mix of imports and computations. Please use separate cells\u201d?\n\nA: You should not have cells that are not exported, *and* contain a mix\nof `import` statements along with other code. For instance, don\u2019t do\nthis in a single cell:\n\n``` python\nimport some_module\nsome_module.something()\n```\n\nInstead, split this into two cells, one which does `import some_module`,\nand the other which does `some_module.something()`.\n\nThe reason for this is that when we create your documentation website,\nwe ensure that all of the signatures for functions you document are up\nto date, by running the imports, exported cells, and\n[`show_doc`](https://nbdev.fast.ai/api/showdoc.html#show_doc) functions\nin your notebooks. When you mix imports with other code, that other code\nwill be run too, which can cause errors (or at least slowdowns) when\ncreating your website.\n\n### Q: Why is nbdev asking for root access? How do I install Quarto without root access?\n\nA: When you setup your first project, nbdev will attempt to\nautomatically download and install [Quarto](https://quarto.org/) for\nyou. This is the program that we use to create your documentation\nwebsite.\n\nQuarto\u2019s standard installation process requires root access, and nbdev\nwill therefore ask for your root password during installation. For most\npeople, this will work fine and everything will be handled automatically\n\u2013 if so, you can skip over the rest of this section, which talks about\ninstalling without root access.\n\nIf you need to install Quarto without root access on Linux, first `cd`\nto wherever you want to store it, then [download\nQuarto](https://quarto.org/docs/get-started/), and type:\n\n``` bash\ndpkg -x quarto*.deb .\nmv opt/quarto ./\nrmdir opt\nmkdir -p ~/.local/bin\nln -s \"$(pwd)\"/quarto/bin/quarto ~/.local/bin\n```\n\nTo use this non-root version of Quarto, you\u2019ll need `~/.local/bin` in\nyour [`PATH` environment\nvariable](https://linuxize.com/post/how-to-add-directory-to-path-in-linux/).\n(Alternatively, change the `ln -s` step to place the symlink somewhere\nelse in your path.)\n\n### Q: Someone told me not to use notebooks for \u201cserious\u201d software development!\n\nA: [Watch this video](https://youtu.be/9Q6sLbz37gk). Don\u2019t worry, we\nstill get this too, despite having used `nbdev` for a wide range of\n\u201cvery serious\u201d software projects over the last three years, including\n[deep learning libraries](https://github.com/fastai/fastai), [API\nclients](https://github.com/fastai/ghapi), [Python language\nextensions](https://github.com/fastai/fastcore), [terminal user\ninterfaces](https://github.com/nat/ghtop), and more!\n\n## Contributing\n\nIf you want to contribute to `nbdev`, be sure to review the\n[contributions\nguidelines](https://github.com/fastai/nbdev/blob/master/CONTRIBUTING.md).\nThis project adheres to fastai\u2019s [code of\nconduct](https://github.com/fastai/nbdev/blob/master/CODE_OF_CONDUCT.md).\nBy participating, you are expected to uphold this code. In general, we\nstrive to abide by generally accepted best practices in open-source\nsoftware development.\n\nMake sure you have `nbdev`\u2019s git hooks installed by running\n[`nbdev_install_hooks`](https://nbdev.fast.ai/api/clean.html#nbdev_install_hooks)\nin the cloned repository.\n\n## Copyright\n\nCopyright \u00a9 2019 onward fast.ai, Inc.\u00a0Licensed under the Apache License,\nVersion 2.0 (the \u201cLicense\u201d); you may not use this project\u2019s files except\nin compliance with the License. A copy of the License is provided in the\nLICENSE file in this repository.\n",
"bugtrack_url": null,
"license": "Apache Software License 2.0",
"summary": "Create delightful software with Jupyter Notebooks",
"version": "2.3.13",
"project_urls": {
"Documentation": "https://nbdev.fast.ai/",
"Homepage": "https://github.com/fastai/nbdev"
},
"split_keywords": [
"nbdev",
"fastai",
"jupyter",
"notebook",
"export"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "45442148be2391edd62b8c88c2114f380141b72276901a53d590be9f769a68e4",
"md5": "b18320d18fc22f4ab10de13366c63fb7",
"sha256": "7e76293c2b38183a103166da4900df6ddefc265fb4a2bb1f265b0d00c6700870"
},
"downloads": -1,
"filename": "nbdev-2.3.13-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b18320d18fc22f4ab10de13366c63fb7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 66098,
"upload_time": "2023-10-19T04:40:00",
"upload_time_iso_8601": "2023-10-19T04:40:00.767463Z",
"url": "https://files.pythonhosted.org/packages/45/44/2148be2391edd62b8c88c2114f380141b72276901a53d590be9f769a68e4/nbdev-2.3.13-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2afcdbed3cce46a63df21ba718e526896e97f5eeb64886ccd85059b352fb8c4e",
"md5": "d3aafb77decd9fdb1e16678db49eb19d",
"sha256": "52691fdc27114524bea4add429e4e0f91bb74d6faa1cda10d85ea7524f234145"
},
"downloads": -1,
"filename": "nbdev-2.3.13.tar.gz",
"has_sig": false,
"md5_digest": "d3aafb77decd9fdb1e16678db49eb19d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 63031,
"upload_time": "2023-10-19T04:40:03",
"upload_time_iso_8601": "2023-10-19T04:40:03.763752Z",
"url": "https://files.pythonhosted.org/packages/2a/fc/dbed3cce46a63df21ba718e526896e97f5eeb64886ccd85059b352fb8c4e/nbdev-2.3.13.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-19 04:40:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fastai",
"github_project": "nbdev",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "nbdev"
}
JSON
