1. Getting Started¶
1.1. IPyPublish Basics¶
This document is written in a Jupyter Notebook (or more precisely an RMarkdown version of the notebook), which is executed and converted auto-magically to the page you are reading. This is the power of IPyPublish!
When analysing data with Python and Jupyter Notebooks, there are three ‘modes’ we will be switching between:
Writing and running analysis code (i.e. populating code cells)
Documenting our analysis (i.e. populating markdown cells)
Marking up and converting our notebooks to a distributable format
IPyPublish, in conjunction with some other great packages, provides enhancements for working in each of these modes and the means to seamlessly switch between them:
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 markdown conversion):
$ conda create --name ipyreport -c conda-forge jupyter pandoc==2.6 $ source activate ipyreport
New in version 0.9.3: ipypublish is now available on Conda (recommended):
$ conda install -c conda-forge ipypublish
ipypublish can also be pip installed into this environment:
$ pip install ipypublish
optionally, to include install dependencies for sphinx exporters:
$ pip install ipypublish[sphinx]
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 provided by the anaconda distribution which can be installed in to a new environment
$ conda create --name ipyreport anaconda
1.3. Basic Conversion¶
The nbpublish script provides terminal access to the notebook conversion application. To see all the options:
$ nbpublish --help
To see all the conversion configurations:
$ nbpublish -le
or to see a subset of configurations with a verbose description, use a regex:
$ nbpublish -le *latex* -lv
To run a basic conversion to PDF and auto-load it in a web browser
$ nbpublish -pdf -lb -f latex_ipypublish_nocode path/to/notebook.ipynb
For a more detailed explanation see the Notebook Conversion section.
The default conversion (
NOToutput any cells that are not tagged with metadata.
output all notebook content by default, use
For existing notebooks: the nb_ipypublish_all and nb_ipypublish_nocode converters (see below) can be helpful for outputting a notebook, with identical content to that input, but with default metatags defining how content is to be output.
The nbpresent script additionally handles serving reveal.js slides to a webbrowser.
$ nbpresent -h $ nbpresent -f slides_ipypublish_nocode path/to/notebook.ipynb
For installation issues, GitHub Actions is used to automatically test updates against multiple Python versions, for Linux, Windows and OSX, Therefore, to troubleshoot any installation/run issues, it is best to first look at the test workflow and 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
detailed log messages of the run are output to both the console and file
(default path: converted/notebook_name.nbpub.log). Try running with
$ nbpublish --log-level debug --print-traceback notebook.ipynb
To debug PDF conversions, use the
--pdf-debug flag. If there is
still an error, please raise an issue on the GitHub
including the run environment and the log file.