...

Documentation projects on ReadTheDocs can be broken. This page is about how to fix them.

Use .readthedocs.yml

The best advice is to configure ReadTheDocs with a .readthedocs.yml file in your repo. ReadTheDocs has docs about how to use it (natch): https://docs.readthedocs.io/en/stable/config-file/v2.html A few of our repos already use this file:

• https://github.com/edx/open-edx-proposals/blob/master/.readthedocs.yaml

• https://github.com/edx/devstack/blob/master/.readthedocs.yml

Getting the login For ReadTheDocs

...

Example PR of doing this in opaque-keys

Use .readthedocs.yml

To fix most problems, you’ll probably need to update the settings. The best advice is to configure ReadTheDocs with a .readthedocs.yml file in your repo. ReadTheDocs has docs about how to use it (natch): https://docs.readthedocs.io/en/stable/config-file/v2.html

A few of our repos already use this file:

• https://github.com/edx/open-edx-proposals/blob/master/.readthedocs.yaml

• https://github.com/edx/devstack/blob/master/.readthedocs.yml

Add a new .readthedocs.yml

If the repo is missing a .readthedocs.yml you’ll want to make a new one. Use this example as a starting point:

# .readthedocs.yml                                                                                                          
# Read the Docs configuration file                                                                                           
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details                                                  
                                                                                                                             
# Required                                                                                                                   
version: 2                                                                                                                   
                                                                                                                             
# Build documentation in the docs/ directory with Sphinx                                                                     
sphinx:                                                                                                                      
   configuration: docs/conf.py                                                                                               
                                                                                                                             
# Optionally build your docs in additional formats such as PDF                                                               
formats:                                                                                                                     
   - pdf                                                                                                                     
   - epub                                                                                                                    
                                                                                                                             
# Optionally set the version of Python and requirements required to build your docs                                          
python:                                                                                                                      
   version: 3.8                                                                                                              
   install:                                                                                                                  
   - requirements: requirements/doc.txt

RTD also has a doc on how to migrate to the config file from the web interface.

Testing .readthedocs.yml Changes

1. Push your changes up to Github on your PR branch.

2. Follow the directions from the Go to the build output section to go to your repos ReadTheDocs project page.

3. Go to the Builds page for your project and build the latest version of the docs.(This will pull all the latest code including any new branches).

   Image Added

4. Go to the Versions page for your project.

   Image Added

5. Under the Activate a Version section, find the name of your PR branch.

6. Click Activate on your PR branch.

7. Set your branch to be active and hidden and then save the changes.

   Image Added

8. Now you should be able to run builds of your branch to test any changes you’re making to the .readthedocs.yml file.

9. Go back to the Builds screen and build your branch as many times as you need while you iterate on changes.

10. When you’re done testing, de-activate your branch on the Versions page.

Common Documentation Building Problems

Wrong Python Version on RTD

If RTD is trying to build the docs using an older version of Python (2.x) you can update that version.

If your repo has a .readthedocss.yml, update the python version in that file and push up a new PR.

If it is still configured via the web interface, consider moving your settings to .readthedocs.yml as a part of the fix. You can also update the setting in the web interface by going to ‘Admin’->'Advanced Settings' and try to re-build the project.

...

If you see a ‘No such file or directory’ message on the requirements file, the issue might be with the config in your repo. Update the path in .

If your repo has a .readthedocss.yml, ensure that the correct path to the requirements file is in there.

If it is still configured via the web interface, consider moving your settings to .readthedocs.yml as a part of the fix. You can also update the setting in the web interface by going to ‘Admin’->'Advanced Settings' to match put in the correct path to the requirements file needed to build the docs.

...