Tools we build

There are several major tools that we have developed, or are contributing to, as a part of this project. This page describes a few major components.

Jupyter Book

Jupyter Book is an open source project for building beautiful, publication-quality books and documents from computational material.

Jupyter Book has the following main features:

• Write publication-quality content in markdown. You can write in either Jupyter markdown, or an extended flavor of markdown with publishing features. This includes support for rich syntax such as citations and cross-references, math and equations, and figures.

• Write content in Jupyter Notebooks, allowing you to include your code and outputs in your book. You can also write notebooks entirely in markdown to execute when you build your book.

• Execute and cache your book’s content. For .ipynb and markdown notebooks, execute code and insert the latest outputs into your book. In addition, cache and re-use outputs to be used later.

• Insert notebook outputs into your content. Generate outputs as you build your documentation, and insert them in-line with your content across pages.

• Add interactivity to your book. You can toggle visibility of cells, connect with an online service like Binder, and include interactive outputs from Jupyter.

• Generate a variety of outputs, including single- and multi-page websites, as well as PDF outputs.

• A command-line interface to quickly generate your books with one command, like so: jupyter-book build mybook/

Note

Jupyter Book gets most of its functionality from the collection of open source tools listed below. You can use each tool on its own for your own purposes, or bring them together with Jupyter Book.

MyST - Markedly Structured Text

(link to documentation)

MyST allows you to write Sphinx documentation entirely in markdown. It is an attempt to have the best of both worlds: the flexibility and extensibility of Sphinx with the simplicity and readability of Markdown.

MyST has the following main features:

• A markdown parser for Sphinx. You can write your entire Sphinx documentation in markdown.

• Call Sphinx directives and roles from within Markdown, allowing you to extend your document via Sphinx extensions.

• Extended Markdown syntax for useful rST features, such as line commenting and footnotes.

• A Sphinx-independent parser of MyST markdown that can be extended to add new functionality and outputs for MyST.

• A superset of CommonMark markdown. Any CommonMark markdown (such as Jupyter Notebook markdown) is natively supported by the MyST parser.

MyST-NB

(link to documentation)

MyST-NB is an open source tool for working with Jupyter Notebooks in the Sphinx ecosystem. It provides the following primary features:

• Parse ipynb files in Sphinx. Directly convert Jupyter Notebooks into Sphinx documents.

• Execute and Cache your notebook content. Save time building your documentation without needing to commit your notebook outputs directly into git.

• Write MyST Markdown. MyST Markdown allows you to write Sphinx roles and directives in markdown.

• Insert notebook outputs into your content. Generate outputs as you build your documentation, and insert them across pages.

• Write Jupyter Notebooks entirely with Markdown. You can define the structure of a notebook in pure-text making it more diff-able.

In addition, there are several options for controlling the look and feel of how your notebooks are used in your documentation.

Sphinx Book Theme

(link to documentation)

This is a lightweight Sphinx theme designed to mimic the look-and-feel of an interactive book. It has the following primary features:

• Bootstrap 4 for visual elements and functionality.

• Flexible content layout that is inspired by beautiful online books, such as the Edward Tufte CSS guide

• Visual classes designed for Jupyter Notebooks. Cell inputs, outputs, and interactive functionality are all supported.

• Launch buttons for online interactivity. For pages that are built with computational material, connect your site to an online BinderHub for interactive content.

Jupyter Cache

(link to documentation)

This packages provides a clear API and CLI for staging, executing and cacheing Jupyter Notebooks. Although there are certainly other use cases, the principle use case this was written for is generating books / websites, created from multiple notebooks (and other text documents), during which it is desired that notebooks can be auto-executed only if the notebook had been modified in a way that may alter its code cell outputs.

Markdown-it-py

(link to documentation)

Markdown parser done right. Fast and easy to extend.

markdown-it-py is a Python port of the very popular markdown-it package. Its goal is to remain as close as possible to the markdown-it API and plugin spec. Here are its main features:

• Follows the CommonMark spec for baseline parsing

• Configurable syntax: You can add new rules and even replace existing ones

• Pluggable: Adds syntax extensions to extend the parser (see the plugin list)

• High speed (see our benchmarking tests)

• Safe by default

A collection of Sphinx extensions

In addition to these major tools described above, the EBP also maintains a number of tools in the Sphinx ecosystem for writing beautiful online books and documents. For example:

• sphinx-copybutton

• sphinx-togglebutton

• sphinx-panels