Read the Docs

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 pre_build job.

To publish your book with Read the Docs, follow these steps:

  1. Get started with Read the Docs. To do so, follow the Read the Docs tutorial. Configure Read the Docs to host a website from your book’s repository.

  2. Create a .readthedocs.yml file in the root of your repository. This file configures the behavior of Read the Docs.

  3. Add a pre_build job to your .readthedocs.yml file. 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.11"
  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.

Tip

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.