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

Ask Ned or Feanil to share the Keeper folder for the readthedocs.org login for the “edx” account.

Go to the build Output

The failing build in RTD(ReadTheDocs) will have a stack trace that you can use to start debugging the build.

...

Many doc projects don’t notify on failure, if . If you know how the owning team wants to be notified for failures, add the relevant e-mail address as a notification channel under ‘Admin’->'Notifications'

...

Docs can often be built locally by going to the docs directory in the repo and running , make html. Add this as a test to CI if the repo doesn’t already build docs as a part of CI.

...

If RTD is trying to build the docs using an older version of pythonPython (2.x) you can update that version 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 ‘Admin’->'Advanced Settings' to match the correct path to the requirements file needed to build the docs.

Missing webhook

The docs might build fine when triggered manually, but not start builds automatically. This means you need to fix the webhook. TODO: add directions here.