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.