Vignette Engine Wrapping Jupyter Notebooks

Calls the 'Jupyter' script 'nbconvert' to create vignettes from notebooks. Those notebooks ('.ipynb' files) are files containing rich text, code, and its output. Code cells can be edited and evaluated interactively. See < https://jupyter.org/> for more information.

nbconvertR

A small shim to use jupyter’s nbconvert as vignette engine and Jupyter notebooks as vignette sources.

To get started, create a notebook in the vignettes/ directory of your package, and a .ipynbmeta file of the same name next to it.

E.g. next to the notebook vignettes/floob.ipynb, create vignettes/floob.ipynbmeta:

%\VignetteIndexEntry{About Floob}
%\VignetteEngine{nbconvertR::nbconvert}

Don’t forget VignetteBuilder: nbconvertR in your DESCRIPTION file!

Options

There are some customization options available that you can put into your .ipynbmeta file.

1. You can use custom templates via %\VignetteTemplate{<format>}{<filename>}.

   E.g. %\VignetteTemplate{latex}{floob.tplx} will result in nbconvert --template floob.tplx ... being called when converting to LaTeX.

2. Another mighty customization option are preprocessors: %\VignettePreprocessors{<format>}{<module>.<Preproc>[, ...]}

   This will pass --<Format>Exporter.preprocessors=["<module>.<Preproc>",...] to nbconvert. It’s possible to specify multiple comma-separated preprocessors in one line.

Installation

The system requirements include nbconvert and pandoc.

nbconvert can easily be installed with the usual python package managers: pip install nbconvert or conda install nbconvert. At least Arch Linux users can find it in the official repositories: pacman -S jupyter-nbconvert

Pandoc is in the repositories of most linux distributions (e.g. apt-get install pandoc or pacman -S pandoc) and Homebrew for OS X (brew install pandoc), and has windows and OS X installers for each release (Download links are below the release notes). Otherwise look here.