|
| 1 | +Preview Documentation from Pull Requests |
| 2 | +======================================== |
| 3 | + |
| 4 | +Read the Docs allows you to build and preview your documentation from pull requests. |
| 5 | +To enable this feature: |
| 6 | + |
| 7 | +#. Go to your project dashboard |
| 8 | +#. Go to :guilabel:`Admin > Advanced settings` |
| 9 | +#. Enable the :guilabel:`Build pull requests for this project` option |
| 10 | +#. Click on :guilabel:`Save` |
| 11 | + |
| 12 | +Features |
| 13 | +-------- |
| 14 | + |
| 15 | +- **Build on Pull Request Events:** We create and build a new version when a pull request is open, |
| 16 | + and when a new commit has been pushed. |
| 17 | + |
| 18 | +- **Build Status Report:** When a build is triggered, a build pending notification is sent with a link to the build log. |
| 19 | + 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. |
| 20 | + |
| 21 | +- **Warning Banner:** A warning banner is shown at the top of the documentation |
| 22 | + to let users know that this isn't the main documentation for the project. |
| 23 | + |
| 24 | + .. note:: Warning banners are available only for :doc:`Sphinx projects </intro/getting-started-with-sphinx>`. |
| 25 | + |
| 26 | +.. figure:: /_static/images/github-build-status-reporting.gif |
| 27 | + :align: center |
| 28 | + :alt: GitHub Build Status Reporting for Pull Requests. |
| 29 | + :figwidth: 80% |
| 30 | + :target: ../_static/images/guides/github-build-status-reporting.gif |
| 31 | + |
| 32 | + GitHub build status reporting |
| 33 | + |
| 34 | +Privacy levels |
| 35 | +-------------- |
| 36 | + |
| 37 | +.. note:: |
| 38 | + |
| 39 | + Privacy levels are only supported on :doc:`/commercial/index`. |
| 40 | + |
| 41 | +All docs built from a pull requests are private by default. |
| 42 | +Currently, this can't be changed, but we are planning to support this. |
| 43 | + |
| 44 | +Limitations |
| 45 | +----------- |
| 46 | + |
| 47 | +- Builds from pull requests have the same memory and time limitations |
| 48 | + :doc:`as regular builds </builds>`. |
| 49 | +- Only available for GitHub and GitLab. |
| 50 | +- Additional formats like PDF and Epub aren't built to produce results quicker. |
| 51 | +- Searches will default to the default experience for your tool. |
| 52 | + This is a feature we plan to add, |
| 53 | + but don't want to overwhelm our search indexes used in production. |
| 54 | +- The built documentation is kept for 90 days after the pull request has been closed or merged. |
| 55 | + |
| 56 | +Troubleshooting |
| 57 | +--------------- |
| 58 | + |
| 59 | +#. **Pull Requests builds are not triggered**. |
| 60 | + We only support GitHub and GitLab currently. |
| 61 | + You need to make sure that your Read the Docs account is connected with that provider. |
| 62 | + You can check this by going to your `profile settings`_. |
| 63 | + |
| 64 | +#. **Build status is not being reported to your VCS provider**. |
| 65 | + You need to make sure that you have granted access to the Read the Docs |
| 66 | + `OAuth App`_ to your personal or organization GitHub account. |
| 67 | + If you do not see "Read the Docs" in the `OAuth App`_ settings, |
| 68 | + you might need to disconnect and reconnect to GitHub service. |
| 69 | + |
| 70 | + Also make sure your webhook is properly setup |
| 71 | + to handle events related to pull requests. You can setup or ``re-sync`` the webhook from your projects admin dashboard. |
| 72 | + Learn more about setting up webhooks from our :doc:`Webhook Documentation </webhooks>`. |
| 73 | + |
| 74 | +.. _profile settings: https://readthedocs.org/accounts/social/connections/ |
| 75 | +.. _OAuth App: https://github.com/settings/applications |
0 commit comments