Workflow combining Asciidoctor with Codes in Jupyter Notebooks.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
output Initial commit. Dec 27, 2018
.gitignore Initial commit. Dec 27, 2018

The Python Quants


Asciidoctor with a Twist

This repository provides a few (unpolished) helper scripts to write larger documents with Asciidoctor that import (Python) code from Jupyter Notebook semi-automatically.

The approach introduced hase been used e.g. to write the book Python for Finance (2nd ed., O'Reilly). See

The repository is authored and maintained by The Python Quants GmbH. © Dr. Yves J. Hilpisch. MIT License.


The following requires a standard Python 3.x installation as well as the installation of Asciidoctor — see

Basic Idea

The basic idea of the approach is to use Asciidoctor as the basis. Codes can be written and stored in Jupyter Notebooks. Tags are added that later (after a parsing step) are used to include code snippets automatically into the Asciidoctor files. The same holds true for images/plots that are created during the execution of a Jupyter Notebook.


The files in the files folder are taken from earlier draft versions of Python for Finance (2nd ed., O'Reilly, They have been modified for the simplified example to follow.

Files and Steps

To render the example files (see files folder) with Asciidoctor, do the following.

First, execute the Jupyter Notebook (code/why_python.ipynb) and save it. Note the tags added in raw cells. Plots are saved automatically (in images folder).

Second, on the shell in the files folder, parse the executed and saved Jupyter Notebook via

python code/why_python.ipynb

This creates a text file with location and name code/why_python.txt.

Third, on the shell, execute

asciidoctor -a stem=latexmath py4fi.asciidoc

to render a HTML version.

Fourth, on the shell, execute

asciidoctor-pdf -r asciidoctor-mathematical -a pdf-style=basic-theme.yml py4fi.asciidoc
rm *.png

to render a PDF version and delete temporary png files.

The file is at the core of the example and the approach presented. It has grown over the course of writing Python for Finance (2nd ed.). However, it has not been reenginered or optimized in any way. Therefore, use it with caution and take it maybe as a starting point for your custom conversions.

Example Output

The following screenshot shows example output from the HTML version.

The following screenshot shows example output from the PDF version.

The Python Quants | @dyjh |