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!
There are some customization options available that you can put into your .ipynbmeta
file.
-
You can use custom templates via
%\VignetteTemplate{<format>}{<filename>}
.E.g.
%\VignetteTemplate{latex}{floob.tplx}
will result innbconvert --template floob.tplx ...
being called when converting to LaTeX. -
Another mighty customization option are preprocessors:
%\VignettePreprocessors{<format>}{<module>.<Preproc>[, ...]}
This will pass
--<Format>Exporter.preprocessors=["<module>.<Preproc>",...]
tonbconvert
. It’s possible to specify multiple comma-separated preprocessors in one line.
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.