Writing a library entirely in notebooks
Project description
Welcome to nbdev
nbdev
is a library that allows you to fully develop a library in jupyter notebooks, putting all your code, tests and documentation in one place. That is: you now have a true literate programming environment, as envisioned by Donald Knuth back in 1983!
Using the interactive environment, you can easily debug and refactor your code. Add #export
flags to the cells that define the functions you want to include in your python modules. Here, for instance, is how combined_cos
is defined and documented in the fastai
library:
{% include image.html alt="Exporting from nbdev" caption="An example of a function defined in one cell (marked with the export flag) and explained, along with a visual example, in the following cells" max-width="700" file="nbs/images/export_example.png"%}
Using notebooks written like this, nbdev
can create and run any of the following with a single command:
- Searchable, hyperlinked documentation
- Python modules, following best practices such as automatically defining
__all__
(more details) with your exported functions, classes, and variables - Pip installers (uploaded to pypi for you)
- Tests (defined directly in your notebooks, and run in parallel)
- Navigate and edit your code in a standard text editor or IDE, and export any changes automatically back into your notebooks
Since you are in a notebook, you can also add charts, text, links, images, videos, etc, that will included automatically in the documentation of your library. The cells where your code is defined will be hidden and replaced by standardized documentation of your function, showing its name, arguments, docstring, and link to the source code on github. For instance, the cells above are converted to:
{% include image.html alt="Documentation in nbdev" caption="An example of automated documentation from the fastai library" max-width="600" file="nbs/images/doc_example.png"%}
See below for Installing and Getting Started. In the other pages of the documentation, you can get more details about:
- the export functionality from jupyter notebooks to a python library
- the cli commands you can use with nbdev in a terminal
- how export2html builds a documentation for your library
- how sync can allow you to export back form the python modules to the jupyter notebook
- how to put tests in your notebooks, which can be run in parallel, and exported to CI from your notebooks
Installing
nbdev is is on PyPI so you can just run:
pip install nbdev
For an editable install, use the following:
git clone https://github.com/fastai/nbdev
pip install -e nbdev
Getting Started
To begin your own project, click here: nbdev template. Fill in the requested info and click Create repository from template, and a new GitHub repo will be created for you.
Now, open your terminal, and clone the repo you just created.
Next, edit the settings.ini
file. Note that it contains all the necessary information for when you'll be ready to package your library, so you shouldn't need to change the setup.py
file provided by the template. The basic structure (that can be personalized provided you change the relevant information in settings.ini
) is that the root of the repo will contain your notebooks, along with a folder docs
where the doc will be auto-generated that contains everything for a jekyll-powered website. Because GitHub Pages supports Jekyll, you can host your site for free on GitHub without any additional setup.
Your settings.ini
is where all parts of nbdev look for any required configuration information. Once you've edited it, run the command nbdev_build_lib
(which is automatically installed for you when you install nbdev
. You'll now find that you have a new directory, with the name of whatever you set lib_name
to in settings.ini
.
Now, run jupyter notebook
, and click 00_core.ipynb
. This is where you'll create your first module! Create Jupyter cells as you would in any notebook. For any cells that you want to be included in your python module, type #export
as the first line of the module.
In the last cell of your notebook, you can then run:
from nbdev.export import *
notebook2script()
Converted 00_export.ipynb.
Converted 01_sync.ipynb.
Converted 02_showdoc.ipynb.
Converted 03_export2html.ipynb.
Converted 04_test.ipynb.
Converted 05_cli.ipynb.
Converted 99_index.ipynb.
Or in the command line, you can run:
nbdev_build_lib
as long as you are somewhere in the folder where you are developing your library. Either of these will do the same thing: update your module to include all exported cells in your notebook.
To enable documentation in your GitHub repo, click 'Settings' on the main repo page, scroll down to 'GitHub Pages', and under 'Source' choose 'master branch /docs folder'. GitHub will then show you a link to your working documentation site.
Finally, edit 99_core.ipynb
. This will be converted into your projects README file, and will also be the index for your documentation. You can use the module you just exported in this library, which means you can show real working code, and actual outputs. Once you have everything as you want it, run nbdev_build_docs
in the terminal. This will export HTML versions of your notebooks to the docs
directory, and will create hyperlinks for any words in backticks (as long as they exist in your module). It will also create a menu for all notebooks you have created, and a table of contents for each.
Adding your project to pypi
If you want people to be able to install your project by just typing pip install your-project
then you need to upload it to pypi. The good news is, we've already created a fully pypi compliant installer for your project! So all you need to do is register at pypi, if you haven't previously done so, and then create a file called ~/.pypirc
with your login details. It should have these contents:
[pypi]
username = your_pypi_username
password = your_pypi_password
To upload your project to pypi, just type make pypi
in your project root directory. Once it's complete, a link to your project on pypi will be printed.
NB: make sure you increment the version number in settings.py
each time you want to push a new release to pypi.
Contributing
If you want to contribute to nbdev
, be sure to review the contributions guidelines. This project adheres to fastai`s code of conduct. By participating, you are expected to uphold this code. In general, the fastai project strives to abide by generally accepted best practices in open-source software development.
Make sure you have the git hooks we use installed by running
nbdev_install_git_hooks
in the cloned repository folder.
Copyright
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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.