Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Next »

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:

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.

  1. Go to https://readthedocs.org/dashboard/

  2. Login Using the credentials from Keeper

  3. Find your failing project in the project list.

  4. Click on the project to go to a project page like: https://readthedocs.org/projects/opaque-keys/

  5. Go to the Builds Section.

  6. Click on a failing build to see the build output.

  7. You should see the build output.

  8. Fix any issues you see.(See the Common Problems section below for help.)

Build docs Feedback Loops

Notify on Failures

Many doc projects don’t notify on failure. 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'

Add doc builds to CI

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.

Example PR of doing this in opaque-keys

Common 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 by going to ‘Admin’->'Advanced Settings' and try to re-build the project.

Missing Requirements Files

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.

  • No labels