Getting Started

Installation

Using Conda is recommended for package management, in order to create self contained environments with specific versions of packages. The main external packages required are the Jupyter notebook and Pandoc (for conversion between file formats):

conda create --name ipyreport -c conda-forge jupyter pandoc

ipypublish can then be installed into this environment:

source activate ipyreport
pip install ipypublish

For converting to PDF, the TeX document preparation ecosystem is required, in particular latexmk), which can be installed from:

• Linux: TeX Live
• macOS (OS X): MacTeX
• Windows: MikTex

For helpful extensions to the notebooks core capabilities, see the Jupyter Notebook Extensions package:

conda install --name ipyreport jupyter_contrib_nbextensions

Additionally, a more extensive setup of useful packages (used to create the examples) are provided by the anaconda distribution which can be installed in to a new environment

conda create --name ipyreport anaconda

Basic Conversion

The nbpublish script handles parsing the notebooks to nbconvert, with the appropriate converter.

nbpublish -h
nbpublish -pdf -f latex_ipypublish_nocode path/to/notebook.ipynb

For a more detailed explanation see the Notebook Conversion section.

The nbpresent script handles serving reveal.js slides to a webbrowser.

nbpresent -h
nbpresent -f slides_ipypublish_nocode path/to/notebook.ipynb

Note that, for offline use, simply download the latest version of reveal.js here, rename the entire folder to reveal.js and place it in the same folder as the converted .slides.html file. The slides can also be save to PDF my appending pdf-export to the url (see here for details).

Troubleshooting

For installation issues, Travis CI is used to automatically test updates against python 2.7 and 3.6, for both Linux and OSX, Therefore, to troubleshoot any installation/run issues, it is best to first look at the travis config and travis test runs for working configurations.

The requirements-lock.txt file can also be used to provide exact versions of working package dependencies.

For conversion issues, for both nbpublish and nbpresent, detailed log messages of the run are output to both the console and file (default path: converted/notebook_name.nbpub.log). To debug conversions, use the --log-level debug and --pdf-debug flags. If there is still an error, please raise an issue on the GitHub repository, including the run environment and the log file.