What is Jupyter Book?¶

According to its own documentation,

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

Jupyter Book is the flagship product of the Executable Book Project, an international collaboration between several universities and software projects seeking to build open source tools that facilitate publishing computational narratives using the Jupyter ecosystem.

Even though Jupyter Book is much younger than Read the Docs as a project, it has become very popular in recent times among scientific software developers and educators. It enables users to write publication-quality content in Markdown thanks to MyST (a Markdown dialect compatible with Sphinx we started promoting back in April this year), use Jupyter notebooks to author content thanks to MyST-NB (featured in our Jupyter on Sphinx guide), easily add interactivity thanks to Thebe, and much more.

Why a change was needed¶

Read the Docs supports two documentation generation systems Sphinx and MkDocs. Adding extra systems is difficult with the current codebase, because it requires lots of effort to match all the features currently supported by the existing ones.

On the other hand, even though Jupyter Book leverages Sphinx “for almost everything that it does”, it purposefully hides some of the Sphinx implementation details from the user to create a more user friendly experience. One of the consequences of this is that the assumptions that Read the Docs makes to build the documentation of Sphinx projects don’t hold: in particular, Jupyter Book uses a declarative configuration file _config.yml that gets translated on the fly to the Sphinx dynamic configuration usually stored in conf.py. As a result, Jupyter Book projects could not be hosted on Read the Docs - until now!

How to deploy a Jupyter Book project to Read the Docs¶

With the current development version of Jupyter Book, you can now export a Sphinx conf.py configuration from the Jupyter Book declarative _config.yml and save it to disk, which allows Read the Docs to build the documentation from it like any other Sphinx project.

The challenge then becomes keeping both configuration files synchronized, since every update to _config.yml or new Jupyter Book release can potentially produce changes in the conf.py. As described in the official documentation, users can either manually export the configuration running a command at will, or set up an automation to do it on every change.

To see this in action, have a look at this example project that contains the bare minimum to make the demo book work on Read the Docs.

We are excited that this is now possible and look forward to seeing more projects built with Jupyter Book!

—

Considering using Read the Docs for your next Sphinx or MkDocs project? Check out our documentation to get started!