|
| 1 | +Preview Documentation from Pull Requests |
| 2 | +======================================== |
| 3 | + |
| 4 | +Read the Docs allows to build and preview your documentation from pull/merge requests. |
| 5 | +You can enable it by: |
| 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/Merge Request Events:** We create and build a new version when a pull/merge request is open, |
| 16 | + and when a new commit has been pushed. |
| 17 | + |
| 18 | +- **Warning Banner:** A warning banner is shown at the top of the documentation |
| 19 | + to let users know that this isn't the main documentation for the project. |
| 20 | + |
| 21 | + .. note:: This feature is only available for :doc:`Sphinx projects </intro/getting-started-with-sphinx>`. |
| 22 | + |
| 23 | +- **Build Status Report:** When a build is triggered, a build pending notification is send with a link to the build log, |
| 24 | + and when the build is done we send a success notification with the link to the preview or a failure notification with a link to the build log. |
| 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/merge 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 | +- Auto-builds for pull/merge requests have |
| 48 | + :doc:`the same limitations as regular documentation builds </builds>`. |
| 49 | +- Only available for GitHub and GitLab. |
| 50 | +- Additional formats like PDF and Epub aren't build. |
| 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/merge request has been closed or merged. |
| 55 | + |
| 56 | +Troubleshooting |
| 57 | +--------------- |
| 58 | + |
| 59 | +After the feature is enabled on your project, |
| 60 | +you might hit one of these issues: |
| 61 | + |
| 62 | +#. **Pull Requests builds are not triggering**. |
| 63 | + We only support GitHub and GitLab currently. You need to make sure |
| 64 | + that your Read the Docs account is connected with that providers social account. |
| 65 | + You can check this by going to your `profile settings`_. |
| 66 | + |
| 67 | +#. **Build status is not being reported on your Pull/Merge Request**. |
| 68 | + You need to make sure that you have granted access to the Read the Docs |
| 69 | + `OAuth App`_ to your/organizations GitHub account. If you do not see "Read the Docs" |
| 70 | + among the `OAuth App`_, you might need to disconnect and reconnect to GitHub service. |
| 71 | + Also make sure your webhook is properly setup |
| 72 | + to handle events. You can setup or ``re-sync`` the webhook from your projects admin dashboard. |
| 73 | + Learn more about setting up webhooks from our :doc:`Webhook Documentation </webhooks>`. |
| 74 | + |
| 75 | +.. _profile settings: https://readthedocs.org/accounts/social/connections/ |
| 76 | +.. _OAuth App: https://github.com/settings/applications |
0 commit comments