Nbdev

Details on setting up nbdev Setup
Author

Benedict Thekkel

Installation

  • Python
  • A Python package manager: we recommend conda or pip - download anaconda
  • Jupyter Notebook - see below
  • nbdev - see below
  • Quarto - see quarto setup

To get Jupyter labs

pip install jupyterlab
mamba install -c conda-forge jupyterlab

To launch jupyter labs

jupyter lab

To install nbdev

pip install nbdev
mamba install -c fastai nbdev

get instructin for quarto with

nbdev_install_quarto

Install the extension by entering:

pip install jupyterlab-quarto

Create an empty GitHub repo

  • make it public

  • add a gitignore file

  • clone it into project location

git clone https://github.com/PROEJECT_NAME.git

RUN Nbdev

Initialise your nbdev repo by entering:

nbdev_new

It may ask you to enter information that it couldn’t infer from git or GitHub.

  • Do a git push to make sure everything is working
git add .
git commit -m'Initial commit'
git push

Go to settings on Github, go to pages, Change Branch to gh-pages

  • Then check on Actions

Useful commands

The next step is to install your package by entering this into your terminal:

pip install -e '.[dev]'

This is the recommended way to make a Python package importable from anywhere in your current environment:

  • -e – short for “editable”, lets you immediately use changes made to your package without having to reinstall, which is convenient for development.
  • . – refers to the current directory.
  • [dev] – includes “development” requirements: other packages that your notebooks use solely for documentation or testing.

Start the preview by entering this into your terminal:

nbdev_preview

Before every git push, run :

nbdev_prepare

Which is the combination of:

nbdev_export

Builds the .py modules from Jupyter notebooks

nbdev_test

Tests your notebooks

nbdev_clean

Cleans your notebooks to get rid of extreanous output for git

nbdev_readme

Updates your repo’s README.md file from your index notebook.

Directives for documentation:

#|hide

Hide cell input and output.

#|echo: <true|false>

Toggle the visibility of code-cell inputs.

#|output: <true|false|asis>

Setting this to false hides the output of a cell. Setting this to asis renders the output as raw markdown.

#|hide_line

Hide a specific line of code in an input cell.

#|code-fold: <show|true>

The #|code-fold directive allows you to collapse code cells. When set to true, the element is collapsed by default, when set to show show the element is shown by default.

Exports

#|default_exp <name>

Names the module where cells with the #|export directive will be exported to by default.

#|export

Exports the items in the cell into the generated module and documentation.

#|exports

A source export. Like #|export but in addition to showing docs via showdoc.show_doc, it also shows the source code.

#|exec_doc

Ensures that a cell is executed each time before generating docs. When a cell does not have this annotation, it is run according to the default rules described here.

#|eval: <true|false>

When set to false, the cell is ignored during testing.

Testing

def say_hello(to):
    "Say hello to somebody"
    return f'Hello {to}!'
say_hello("Isaac")
'Hello Isaac!'

This is a test too! When you run nbdev_test it will execute this cell (and all other test cells) and fail if they raise any exceptions.

For tests, it’s preferred to use more explicit asserts:

assert say_hello("Hamel") == "Hello Hamel!"
from fastcore.test import *
test_eq(say_hello("Hamel"), "Hello Hamel!")

Using

$$\sum_{i=1}^{k+1}i$$

Which is rendered as: \[\sum_{i=1}^{k+1}i\]

This version is displayed inline: $\sum_{i=1}^{k+1}i$ . You can include text before and after.

Becomes: This version is displayed inline: \(\sum_{i=1}^{k+1}i\) . You can include text before and after.

Back to top