https://blog.readthedocs.com 2023-07-08T10:50:30.266533+00:00 ABlog https://blog.readthedocs.com/jupyter-book-read-the-docs/ 2021-11-11T00:00:00+00:00 Juan Luis Cano Rodríguez <section id="read-the-docs-jupyter-book"> <p>We are proud to announce that now Jupyter Book projects are supported on Read the Docs!</p> <p>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 <a class="reference internal" href="../../../newsletter-april-2021/"><span class="doc">back in April this year</span></a>, and we wrote a guide on <a class="reference external" href="https://docs.readthedocs.io/en/stable/guides/jupyter.html" title="(in Read the Docs user documentation v9.15.0)"><span class="xref std std-doc">using Jupyter notebook with Sphinx</span></a> that benefitted a lot from their feedback.</p> <p>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.</p> <section id="what-is-jupyter-book"> <h2>What is Jupyter Book?</h2> <p>According to <a class="reference external" href="https://jupyterbook.org/">its own documentation</a>,</p> <blockquote> <div><p>Jupyter Book is an open source project for building beautiful, publication-quality books and documents from computational material.</p> </div></blockquote> <p>Jupyter Book is the flagship product of <a class="reference external" href="https://executablebooks.org/">the Executable Book Project</a>, an international collaboration between several universities and software projects seeking to build open source tools that facilitate publishing computational narratives using the Jupyter ecosystem.</p> <p>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 <a class="reference external" href="https://myst-parser.readthedocs.io/">MyST</a> (a Markdown dialect compatible with Sphinx <a class="reference internal" href="../../../newsletter-april-2021/"><span class="doc">we started promoting back in April this year</span></a>), use Jupyter notebooks to author content thanks to <a class="reference external" href="https://myst-nb.readthedocs.io/">MyST-NB</a> (featured in our <a class="reference external" href="https://docs.readthedocs.io/en/stable/guides/jupyter.html" title="(in Read the Docs user documentation v9.15.0)"><span class="xref std std-doc">Jupyter on Sphinx guide</span></a>), easily add interactivity thanks to <a class="reference external" href="https://thebe.readthedocs.io">Thebe</a>, and much more.</p> </section> <section id="why-a-change-was-needed"> <h2>Why a change was needed</h2> <p>Read the Docs supports two documentation generation systems <a class="reference external" href="https://www.sphinx-doc.org/">Sphinx</a> and <a class="reference external" href="https://www.mkdocs.org/">MkDocs</a>. 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.</p> <p>On the other hand, even though <a class="reference external" href="https://jupyterbook.org/explain/sphinx.html#jupyter-book-is-a-distribution-of-sphinx">Jupyter Book leverages Sphinx “for almost everything that it does”</a>, 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 <code class="docutils literal notranslate"><span class="pre">_config.yml</span></code> that gets translated on the fly to the Sphinx dynamic configuration usually stored in <code class="docutils literal notranslate"><span class="pre">conf.py</span></code>. As a result, Jupyter Book projects could not be hosted on Read the Docs - until now!</p> </section> <section id="how-to-deploy-a-jupyter-book-project-to-read-the-docs"> <h2>How to deploy a Jupyter Book project to Read the Docs</h2> <p>With the current development version of Jupyter Book, you can now export a Sphinx <code class="docutils literal notranslate"><span class="pre">conf.py</span></code> configuration from the Jupyter Book declarative <code class="docutils literal notranslate"><span class="pre">_config.yml</span></code> and save it to disk, which allows Read the Docs to build the documentation from it like any other Sphinx project.</p> <p>The challenge then becomes keeping both configuration files synchronized, since every update to <code class="docutils literal notranslate"><span class="pre">_config.yml</span></code> or new Jupyter Book release can potentially produce changes in the <code class="docutils literal notranslate"><span class="pre">conf.py</span></code>. As described in <a class="reference external" href="https://jupyterbook.org/en/stable/publish/readthedocs.html" title="(in Python)"><span class="xref std std-doc">the official documentation</span></a>, users can either <a class="reference external" href="https://jupyterbook.org/en/stable/sphinx/index.html#sphinx-convert" title="(in Python)"><span class="xref std std-ref">manually export the configuration</span></a> running a command at will, or set up an automation to do it on every change.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>Update April 4th, 2022</p> <p>This process is now simplified by using Read the Docs’ <code class="docutils literal notranslate"><span class="pre">build.jobs.pre_build</span></code> config key and does not requires having the <code class="docutils literal notranslate"><span class="pre">conf.py</span></code> in sync with <code class="docutils literal notranslate"><span class="pre">_config.yml</span></code> and pushed to the repository anymore. Check out Jupyter’s <a class="reference external" href="https://jupyterbook.org/en/stable/publish/readthedocs.html" title="(in Python)"><span class="xref std std-doc">official documentation</span></a> to find out the configuration required.</p> </div> <p>To see this in action, have a look at <a class="reference external" href="https://github.com/astrojuanlu/jupyterbook-on-read-the-docs">this example project</a> that contains the bare minimum to make <a class="reference external" href="https://jupyterbook.org/en/stable/start/create.html" title="(in Python)"><span class="xref std std-doc">the demo book</span></a> work on Read the Docs.</p> <p>We are excited that this is now possible and look forward to seeing more projects built with Jupyter Book!</p> <p>—</p> <p>Considering using Read the Docs for your next Sphinx or MkDocs project? Check out <a class="reference external" href="https://docs.readthedocs.io/">our documentation</a> to get started!</p> </section> </section>

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.

2021-11-11T00:00:00+00:00