Read the Docs#
Read the Docs is a web service for hosting documentation online. They offer free web hosting for open source projects, sustained by ethical advertising that is inserted into pages. These ads can also be removed with a small monthly payment to help sustain the project.
Read the Docs builds Sphinx websites, and does not support Jupyter Book directly.
However, you can convert your book to a Sphinx website in order to publish with Read the Docs.
This can be automated with a Read the Docs
To publish your book with Read the Docs, follow these steps:
.readthedocs.ymlfile in the root of your repository. This file configures the behavior of Read the Docs.
pre_buildjob to your
.readthedocs.ymlfile. Read the Docs allows you to run extra scripts before and after your documentation is built. You can use this to generate the Sphinx configuration for your Jupyter Book before Read the Docs tries to build it. For example, this configuration is used to build this book:
version: 2 build: os: ubuntu-22.04 tools: python: "3.8" jobs: pre_build: # Generate the Sphinx configuration for this Jupyter Book so it builds. - "jupyter-book config sphinx docs/" python: install: - method: pip path: . extra_requirements: - sphinx sphinx: builder: html fail_on_warning: true
See the Read the Docs Config File reference for a full reference to the configuration file options.
Read the Docs should now automatically generate the Sphinx configuration for your book and build your book’s HTML to host it online.
You can also get started by using this example project from Read the Docs:
The project itself can be copied and customized, or you can use it as a reference when you start a Jupyter Book project from scratch that you wish to publish on Read the Docs.