Your docs depend on tools and other dependencies to be built. If your docs don’t have reproducible builds, an update in a dependency can break your builds when least expected, or make your docs look different from your local version. This guide will help you to keep your builds working over time, and in a reproducible way.
To test your build process, you can build them locally in a clean environment (this is without any dependencies installed). Then you should make sure you are running those same steps on Read the Docs.
You can configure how your project is built from the web interface (Admin tab), or by using a configuration file (recommended). If you aren’t familiar with these tools, check our docs:
You can see the exact commands that are run on Read the Docs by going to the Builds tab of your project.
If you use the web interface to configure your project, the options are applied to all versions and builds of your docs, and can be lost after changing them over time. Using a configuration file provides you per version settings, and those settings live in your repository.
A configuration file with explicit dependencies looks like this:
# File: .readthedocs.yaml version: 2 # Build from the docs/ directory with Sphinx sphinx: configuration: docs/conf.py # Explicitly set the version of Python and its requirements python: version: 3.7 install: - requirements: docs/requirements.txt
# File: docs/requirements.txt # Defining the exact version will make sure things don't break sphinx==3.4.3 sphinx_rtd_theme==0.5.1 readthedocs-sphinx-search==0.1.0
By default Read the Docs will install the tool you chose to build your docs, and other dependencies, this is done so new users can build their docs without much configuration.
We highly recommend not to assume these dependencies will always be present or that their versions won’t change. Always declare your dependencies explicitly using a configuration file, for example:
- ✅ Good:
Your project is declaring the Python version explicitly, and its dependencies using a requirements file.
# File: .readthedocs.yaml version: 2 sphinx: configuration: docs/conf.py python: version: 3.7 install: - requirements: docs/requirements.txt
- ❌ Bad:
Your project is relying on the default Python version and default installed dependencies.
# File: .readthedocs.yaml version: 2 sphinx: configuration: docs/conf.py
As you shouldn’t rely on implicit dependencies, you shouldn’t rely on undefined versions of your dependencies. Some examples:
- ✅ Good:
The specified versions will be used for all your builds, in all platforms, and won’t be updated unexpectedly.
# File: docs/requirements.txt sphinx==3.4.3 sphinx_rtd_theme==0.5.1 readthedocs-sphinx-search==0.1.0rc3
# File: docs/environment.yaml name: docs channels: - conda-forge - defaults dependencies: - sphinx==3.4.3 - nbsphinx==0.8.1 - pip: - sphinx_rtd_theme==0.5.1
- ❌ Bad:
The latest or any other already installed version will be used, and your builds can fail or change unexpectedly any time.
# File: docs/requirements.txt sphinx sphinx_rtd_theme readthedocs-sphinx-search
# File: docs/environment.yaml name: docs channels: - conda-forge - defaults dependencies: - sphinx - nbsphinx - pip: - sphinx_rtd_theme
Remember to update your docs’ dependencies from time to time to get new improvements and fixes. It also makes it easy to manage in case a version reaches it’s end of support date.