Preview Documentation from Pull Requests

Read the Docs allows you to build and preview your documentation from pull requests. To enable this feature:

  1. Go to your project dashboard

  2. Go to Admin > Advanced settings

  3. Enable the Build pull requests for this project option

  4. Click on Save

Features

  • Build on Pull Request Events: We create and build a new version when a pull request is open, and when a new commit has been pushed.

  • Build Status Report: When a build is triggered, a build pending notification is sent with a link to the build log. When the build finishes we send a success notification with the link to the preview or a failure notification with a link to the build log.

  • Warning Banner: A warning banner is shown at the top of the documentation to let users know that this isn’t the main documentation for the project.

    Note

    Warning banners are available only for Sphinx projects.

GitHub Build Status Reporting for Pull Requests.

Fig. 6 GitHub build status reporting

Privacy levels

Note

Privacy levels are only supported on Read the Docs for Business.

All docs built from a pull requests are private by default. Currently, this can’t be changed, but we are planning to support this.

Limitations

  • Builds from pull requests have the same memory and time limitations as regular builds.

  • Only available for GitHub and GitLab.

  • Additional formats like PDF and Epub aren’t built to produce results quicker.

  • Searches will default to the default experience for your tool. This is a feature we plan to add, but don’t want to overwhelm our search indexes used in production.

  • The built documentation is kept for 90 days after the pull request has been closed or merged.

Troubleshooting

  1. Pull Requests builds are not triggered. We only support GitHub and GitLab currently. You need to make sure that your Read the Docs account is connected with that provider. You can check this by going to your profile settings.

  2. Build status is not being reported to your VCS provider. You need to make sure that you have granted access to the Read the Docs OAuth App to your personal or organization GitHub account. If you do not see “Read the Docs” in the OAuth App settings, you might need to disconnect and reconnect to GitHub service.

    Also make sure your webhook is properly setup to handle events related to pull requests. You can setup or re-sync the webhook from your projects admin dashboard. Learn more about setting up webhooks from our Webhook Documentation.