...

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.

   Image Modified

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

5. Go to the Builds Section.

   Image Modified

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

   Image Modified

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

...

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 Modified

4. Go to the Versions page for your project.

   Image Modified

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 (it will be built) and hidden (it won’t be listed in the versions list) and then save the changes.

   Image Modified

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

...

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

1. Visit the Admin - Integrations section of the project dashboard

2. You need a “GitHub incoming webhook.” If it’s not there, click “Add integration.”

3. Select “GitHub incoming webhook” from the Integration type dropdown.

4. ReadTheDocs will try to add the webhook to GitHub, but will likely fail (TODO: why?)

5. Copy the URL that starts “readthedocs.org/api/v2/…”

6. In GitHub, go to the repo Settings - Webhooks. Click “Add webhook”

7. Paste the URL you copied into the Payload URL. Make sure it starts with “https://”

8. Choose “Let me select individual events” then choose these events:

   1. Branch or tag creation

   2. Branch or tag deletion

   3. Pull requests

   4. Pushes

9. Finish with “Add webhook”