Questions
Objectives
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:
nbfancy init
nbfancy rerun
nbfancy render
nbfancy html
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)
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
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)
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)
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)
init
rerun
render
provides additional rich reatures to makdown cellshtml