s

Nbdev tutorial

By Angela C

April 29, 2021 in nbdev jupyter

Reading time: 4 minutes.

Following the Minimal end-to-end example of creating a nbdev project from scratch.

I have already followed the general tutorial to get nbdev up and running and hosted on GitHub Pages.

There is also a tutorial for completing an entire nbdev-based project from start to finish utilizing only Google Colaboratory which is a free alternative Jupyter environment with GPU capabilities. (There is also a Colab Pro option).

  1. Use the nbdev_template provided by fastai at https://github.com/fastai/nbdev_template to create a new repository.
  • Add a description of the project
  • Public repo
  1. Modify configuration files

  • Edit the settings.ini which are required for hosting documentation on GitHub Pages.

  • Go the the GutHub Pages settings and edit the Source to build the GitHub Pages site from the /docs folder of the master branch. While the message might indicate that the site is published, it won’t actually be there yet as the index.html file has yet to be created.

  • Clone the repo git clone https://github.com/user/deck_of_cards.git

  • cd into the repo

  • Install nbdev if not already installed.

  • Install githooks. nbdev_install_git_hooks

  1. Write code into a Jupyter notebook

For this minimal example we just copy some code provided from Card module from the ThinkPython2 repo as outlined in step 3.

(When copying and pasting code from python files into a Jupyter notebook, copy the whole file into a single cell, then use ctrl-shift-minus to split the code into separate cells.)

  • Export to modules flag
    If the following code is placed in the first cell, #default_exp card, the argument card means that the code exported from the notebook will be placed in the destination card.py by default.

Other Flags

nbdev uses special comments, or flags, as a markup language that allows you to control various aspects of the docs and how code is exported to modules, and how code is tested.

  • #hide this comment instructs nbdev to hide a cell when generating the docs.

  • #export instructs nbdev to export a cell to the appropriate python file. Without any argument this will default to the module specified by #default_exp.

Documentation and Tests

With nbdev docs, tests and source codes can be organised into a single context.

  • markdown cells for documentation
  • assert statements can be used for testing
  • nbdev has a Continuous Integration system.
  1. Edit the index.ipynb file

  • nbdev repositories require a notebook named index.ipynb which is included in the repository when using the template.

  • index.ipynb will become both the README.md for the repo as well as the home page index.html for the documention.

  • The first cell of the index.ipynb template contains the following code:

#hide
from your_lib.core import *`

This should be commented out or removed until the module being created is finished and then it can be replaced with the appropriate import statement.

  1. Convert notebooks to python modules and docs

  • run nbdev_build_lib from the root of the repo. This converts Jupyter notebooks to source code. Notebook cells tagged with #export will be exported to the appropriate python module. 00_cards.ipynb gets converted to card.py.

  • run nbdev_test_nbs to run the code and tests in all the notebooks.

  • To preview the docs run the command make docs_serve from the root of the repo. To do this you need to have jekyll / rubygems installed. This runs the CLI command nbdev_build_docs for you and allows you to preview the docs locally. For now I will just run this nbdev_build_docs command from the terminal in the root of the repo.

  • The first H1 heading in the index.ipynb file becomes a heading while the note block API Details becomes the summary.

  • nbdev automatically renders a table of content (based on markdown headings).

  • nbdev renders the signature of a class or function as a heading.

  • nbdev adds a link to the corresponding source code with the command nbdev_build_lib.

  • Docstrings in functions / classes is also rendered as markdown documentation.

  • The rest of the notebook is rendered by converting the markdown into HTML and will show inputs and outputs of cells including plots etc. Flags can be used to hide entire cells, hide cell input or output using.

  • nbdev supports special block quotes that will be rendered as coloured boxes in the documentation.

  • Words surrounded by backticks will automatically be hyperlinked to the associated documentation where appropriate.

  • After editing the docs run nbdev_build_docs to re-render them.

  1. Push to Github and view hosted docs on GitHub Pages
  • git status
  • git add .
  • git commit -m"commit message"
  • git push

Pushing to GitHub automatically triggers continuous integration using GitHub Actions.

  • After the files are pushed to GitHub it will rebuild the docs automatically.
  • GitHub Pages needs to be enabled for the site to be published. The colour background will change from blue (ready to be published) to green when the page has been built. Click the URL (also in the About / Website setting of the repo page) to go to the URL of the page.

I will come back to the next step of the tutorial which is to add more code in a new notebook that imports the code from the other notebook. For now the site is deployed here.

References

Related Pages