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:
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 listed in conda_packages.txt and an environment can be created directly from this file using conda:
conda create --name ipyreport -c conda-forge -c matsci --file conda_packages.txt
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 Controlling Content Output 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.
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.
Examples¶
See Example.ipynb, Example.pdf, Example.html and Example.slides.html for an example of the potential input/output.
Or, for a practical example of the ipypublish capability, see these documents on Atomic 3D Visualisation: Notebook, PDF, HTML or Reveal.JS slideshow.