Build¶

Overview:

Teaching: 10 min
Exercises: 0 min

Questions

How do I build a lesson?

Objectives

Understand the 4 key steps in a build

The main program for NBfancy is the command line program nbfancy, which we saw in the previous section. Typical usage is nbfancy <verb> [options], where <verb> is some action, and [options] are additional options for that action.

For available actions, we can use the --help flag.

!nbfancy --help

usage: nbfancy [-h] {init,hello,configure,rerun,render,html}

positional arguments:
  {init,hello,configure,rerun,render,html}
                        action to perform. Try adding --help to one of these
                        options for more usage information

optional arguments:
  -h, --help            show this help message and exit

A typical build consists of four steps:

Initialisation with nbfancy init
Re-execution with nbfancy rerun
Rendering with nbfancy render
Publising to website with nbfancy html

Initialisation¶

To start making training material we initialise a directory with the nbfancy init [dir] command:

!nbfancy init example

By default init will copy the template lesson to the current working directory, or optional directory argument if provided, to get you started:

.
├── code
├── config
│   ├── footer.ipynb
│   └── header.ipynb
├── data
├── images
└── nbplain
    ├── 00_schedule.ipynb
    ├── 01_untitled_episode.ipynb
    └── 99_episode_template.ipynb

5 directories, 5 files

For more information about further options for init you can look at the help.

!nbfancy init --help

usage: nbfancy init [-h] [--extra_conf] [--include {tutorial,template,none}]
                    [dir]

positional arguments:
  dir                   Directory to initialise (default:
                        /home/travis/build/JDBetteridge/nbfancy/gh-
                        pages/nbplain)

optional arguments:
  -h, --help            show this help message and exit
  --extra_conf          Initialise additional configuration files (default:
                        False)
  --include {tutorial,template,none}
                        Fill nbplain directory with examples (default:
                        template)

Re-execution¶

In order to reduce issues associated with out of order execution, unexecuted cells it is strongly recommended that all notebooks that form a lesson are cleared and re-executed. This can be done quickly and easily with the nbfancy rerun command.

Re-executing all the notebooks in order can be thought of as automated testing for the code in a lesson, ensuring that someone following along in a lesson won't encounter errors.

Note that if you intend to preserve partially executed notebooks/out-of-order execution, you should omit this step.

%%bash2
cd example
nbfancy rerun

Reading input file: 00_schedule.ipynb
Writing output file: 00_schedule.ipynb
Reading input file: 01_untitled_episode.ipynb
Writing output file: 01_untitled_episode.ipynb
Reading input file: 99_episode_template.ipynb
Writing output file: 99_episode_template.ipynb

What's this magic?

As part of NBfancy we have implemented a thin wrapper around the %%bash magic available in notebooks, which we have called %%bash2. This just keeps track of what directory we are in, so as to keep the content close to what you would type at the command line. %%bash2 magic is available as part of NBfancy, to find out more, see this lesson.

Further options for rerun are listed in the help.

!nbfancy rerun --help

usage: nbfancy rerun [-h] [--output_dir OUTPUT_DIR] [--clear_only]
                     [--allow_errors] [--timeout TIMEOUT]
                     [input_dir]

positional arguments:
  input_dir             Plain notebook directory (default: nbplain)

optional arguments:
  -h, --help            show this help message and exit
  --output_dir OUTPUT_DIR
                        Name of directory for re-evaluated notebooks (default:
                        None)
  --clear_only          Clear the cells, but do not re-evaluate (default:
                        False)
  --allow_errors        Continue running notebook even if errors occur
                        (default: False)
  --timeout TIMEOUT     Number of seconds to allow each cell to run for
                        (default: 60)

Rendering¶

Keywords in notebooks can be processed and marked up by running the nbfancy render command. By default this creates a new directory nbfancy containing a rendered versions of the notebooks in nbplain, with cells containing keywords decorated with the respective environments (see environments section).

%%bash2
nbfancy render

Reading input file: 00_schedule.ipynb
Writing output file: 00_schedule.ipynb
Reading input file: 01_untitled_episode.ipynb
Writing output file: 01_untitled_episode.ipynb
Reading input file: 99_episode_template.ipynb
Writing output file: 99_episode_template.ipynb
Writing output file: 99_episode_template-soln.ipynb

As always further options for render are available in the help.

!nbfancy render --help

usage: nbfancy render [-h] [--output_dir OUTPUT_DIR] [-c CONFIG] [input_dir]

positional arguments:
  input_dir             Plain notebook directory (default: nbplain)

optional arguments:
  -h, --help            show this help message and exit
  --output_dir OUTPUT_DIR
                        Directory to output rendered notebooks to (default:
                        nbfancy)
  -c CONFIG, --config CONFIG
                        Custom configuration directory (default: config)

Publishing¶

Once you have checked the contents of the rendered notebooks, the whole lesson can be built into a website by running the nbfancy html command.

%%bash2
nbfancy html

Reading input file: 00_schedule.ipynb
Writing output file: 00_schedule.html
Reading input file: 01_untitled_episode.ipynb
Writing output file: 01_untitled_episode.html
Reading input file: 99_episode_template.ipynb
Writing output file: 99_episode_template.html
Reading input file: 99_episode_template-soln.ipynb
Writing output file: 99_episode_template-soln.html
Reading redirect template
Reading redirect file

Additional options for html are given by help.

!nbfancy html --help

usage: nbfancy html [-h] [--output_dir OUTPUT_DIR] [--include_slides]
                    [--redirect REDIRECT]
                    [input_dir]

positional arguments:
  input_dir             Fancy notebook directory (default: nbfancy)

optional arguments:
  -h, --help            show this help message and exit
  --output_dir OUTPUT_DIR
                        Directory to output html pages to (default: html)
  --include_slides      Includes html slides in slides directory inside
                        output_dir (default: False)
  --redirect REDIRECT   page to automatically redirect to (default:
                        00_schedule.html)

Key Points:

A directory is initialised using init
The contents of a notebook can be cleared and re-executed using rerun
render provides additional rich reatures to makdown cells
A website of the material is generated using html