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. This file can configure the behavior of Read the Docs. See the ReadTheDocs documentation on its use.

  3. Add a pre_build job to your .readthedocs.yml file. ReadTheDocs 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, see the ReadTheDocs configuration that 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 ReadTheDocs jobs documentation for more information.

Read the Docs should now automatically generate the Sphinx configuration for your book and build your book’s HTML to host it online.