Jupyter Book :heart: Read the Docs

--- tags: Read the Docs date: Nov 11, 2021 meta: Jupyter Book is now supported on Read the Docs, in this post we explain what is needed to make it work. --- # Jupyter Book :heart: Read the Docs [intro about the things we have collaborated on in the past months, will write it later] ## What is Jupyter Book? According to [its own documentation](https://jupyterbook.org/), > 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](https://executablebooks.org/), an international collaboration between several universities and software projects seeking to build open source tools that facilitate publishing computational narratives using the Jupyter ecosystem. Jupyter Book enables users to write publication-quality content in Markdown thanks to [MyST](https://myst-parser.readthedocs.io/) (a Markdown dialect compatible with Sphinx [we started promoting back in April this year](https://blog.readthedocs.com/newsletter-april-2021/)), use Jupyter notebooks to author content thanks to [MyST-NB](https://myst-nb.readthedocs.io/) (featured in our [Jupyter on Sphinx guide](https://docs.readthedocs.io/en/stable/guides/jupyter.html)), easily add interactivity thanks to [Thebe](https://thebe.readthedocs.io), and much more. ## Why a change was needed Read the Docs supports two documentation generation systems: [Sphinx](https://www.sphinx-doc.org/) and [MkDocs](https://www.mkdocs.org/). 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"](https://jupyterbook.org/explain/sphinx.html#jupyter-book-is-a-distribution-of-sphinx), 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 do 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](https://jupyterbook.org/publish/readthedocs.html), users can either [manually export the configuration](https://jupyterbook.org/sphinx/index.html#convert-your-jupyter-book-into-a-sphinx-website) running a command at will, or [set up an automation to do it on every change](https://jupyterbook.org/sphinx/index.html#sphinx-convert-pre-commit). To see this in action, have a look at [this example project](https://github.com/astrojuanlu/jupyterbook-on-read-the-docs) that contains the bare minimum to make [the demo book](https://jupyterbook.org/start/create.html#quickly-generate-a-sample-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!