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 thisREADME.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.
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/index.html
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:
use your existing project repository or create a new repository on GitHub, GitLab, Bitbucket or another host supported by Read the Docs
copy
.readthedocs.yaml
and thedocs/
folder into your project.if you want to have a README on GitHub, create a
README.rst
which will be included inindex.md
.if you do not want your README from GitHub included in the docs, edit Γ¬ndex.md` and remove the
eval-rst
block that includes it.if you don't already have a
.gitignore
, use the one from the project file -- otherwise add these lines:/docs/conf.py /docs/_build
customize all the files, replacing example contents.
rebuild the documenation locally to see that it works.
finally, register your project on Read the Docs, see Importing Your Documentation.
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.