Read the Docs ❤️ Jupyter Book¶
We are proud to announce that now Jupyter Book projects are supported on Read the Docs!
Both Read the Docs and The Executable Book Project, the folks behind Jupyter Book, share a common passion for documentation, and we have been collaborating on various topics for some time already. For example, we started promoting MyST in favor of our recommonmark back in April this year, and we wrote a guide on using Jupyter notebook with Sphinx that benefitted a lot from their feedback.
Now we are happy to announce that Jupyter Book itself is supported on Read the Docs, after some thorough discussion about the possible implementations and thanks in large part to the Jupyter Book developers, who addressed all the minor incompatibilities that prevented this from happening.
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
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
that gets translated on the fly to the Sphinx dynamic configuration usually stored in
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
from the Jupyter Book declarative
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
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.
Update April 4th, 2022
This process is now simplified by using Read the Docs’
key and does not requires having the
conf.py in sync with
_config.yml and pushed to the repository anymore.
Check out Jupyter’s official documentation to find out the configuration required.
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!