Example: Jupyter Book for Read the Docs

This example shows a Jupyter Book project with Read the Docs. You're encouraged to view it to get inspiration and copy & paste from the files in the source code. If you are using Read the Docs for the first time, have a look at the official Read the Docs Tutorial. If you are using Jupyter Book for the first time, have a look at the official Jupyter Book documentation.

📚 docs/

A basic Jupyter Book project lives in docs/. All the *.md make up sections in the documentation, intro.md is the starting page and includes this README.rst.

⚙️ .readthedocs.yaml

Read the Docs Build configuration is stored in .readthedocs.yaml.

⚙️ docs/_config.yml

This is the configuration for Jupyter Book which is used to generate a Sphinx-configuration on-the-fly. However, the Sphinx conf.py file is NOT managed in a git repository, as it is managed by Jupyter Book!

📍 docs/requirements.txt

These dependencies need to be installed for Jupyter Book to work. If you are familiar with Python, you might notice that the dependencies are not pinned. This is the default method for Jupyter Book - on one hand it gives you the latest version each time Read the Docs builds your documentation; but on the other hand, your build can fail in the future if an incompatible version of jupyter-book is released.

💡 Extension: Intersphinx

Using this extension, we refer directly to sections in other projects that use Sphinx.

💡 Extension: sphinx-hoverxref

A floating window (also known as a "tooltip" or "modal dialogue") appears when the mouse curser hovers a cross references to another section of the documentation or another documentation project referenced with Intersphinx.

🔢 Simplified versioning

In this example, we maintain a single version of the rendered documentation by automatically building and rendering everything that is added to the main branch. This is different from many software projects where several versions of the docs may be published for each new release.

🔢 Pull Request builds

Every time a change in a Pull Request on the GitHub repository happens, users can open an automatically built Pull Request preview.

⁉️ Questions / comments

If you have questions related to this example, feel free to can ask them as a GitHub issue here.

Example Project usage

This project has a standard Jupyter Book layout which is built by Read the Docs almost the same way that you would build it locally (on your own laptop!).

You can build and view this documentation project locally - we recommend that you activate a local Python virtual environment first:

# Install required Python dependencies (Sphinx etc.)
pip install -r docs/requirements.txt

# Run Jupyter Book
jupyter-book build docs/

# View the docs with for instance firefox
firefox docs/_build/html/index.html

Using the example in your own project

If you are new to Read the Docs, you may want to refer to the Read the Docs User documentation.

If you are copying this code in order to get started with your documentation, you need to:

1. use your existing project repository or create a new repository on GitHub, GitLab, Bitbucket or another host supported by Read the Docs

2. copy .readthedocs.yaml and the docs/ folder into your project.

3. if you want to have a README on GitHub, create a README.rst which will be included in intro.md.

4. if you do not want your README from GitHub included in the docs, edit intro.md and remove the eval-rst block that includes it.

5. if you don't already have a .gitignore, use the one from the project file -- otherwise add these lines:

   /docs/conf.py
   /docs/_build
   

6. customize all the files, replacing example contents.

7. rebuild the documenation locally to see that it works.

8. finally, register your project on Read the Docs, see Importing Your Documentation.

Read the Docs Tutorial

To get started with Read the Docs, you may also refer to the Read the Docs Tutorial. It provides a full walk-through of building an example project similar to the one in this repository.