From f6cbec13095d919f3dab1ab645d6ba74a054e925 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Tue, 12 Jan 2021 19:46:40 -0500 Subject: [PATCH 1/5] Update docs about preview from pull/merge requests --- .../github-build-status-reporting.gif | Bin .../autobuild-docs-for-pull-requests.rst | 86 ------------------ docs/guides/build-notifications.rst | 2 +- docs/guides/platform.rst | 1 - docs/index.rst | 4 +- docs/pull-requests.rst | 73 +++++++++++++++ 6 files changed, 77 insertions(+), 89 deletions(-) rename docs/_static/images/{guides => }/github-build-status-reporting.gif (100%) delete mode 100644 docs/guides/autobuild-docs-for-pull-requests.rst create mode 100644 docs/pull-requests.rst diff --git a/docs/_static/images/guides/github-build-status-reporting.gif b/docs/_static/images/github-build-status-reporting.gif similarity index 100% rename from docs/_static/images/guides/github-build-status-reporting.gif rename to docs/_static/images/github-build-status-reporting.gif diff --git a/docs/guides/autobuild-docs-for-pull-requests.rst b/docs/guides/autobuild-docs-for-pull-requests.rst deleted file mode 100644 index 8c2ba786bcb..00000000000 --- a/docs/guides/autobuild-docs-for-pull-requests.rst +++ /dev/null @@ -1,86 +0,0 @@ -Autobuild Documentation for Pull Requests -========================================= - -Read the Docs allows autobuilding documentation for pull/merge requests for GitHub or GitLab projects. -You can enable it by: - -.. tabs:: - - .. tab:: |org_brand| - - You can turn PR builds on and off via an admin setting: - - * Go to :guilabel:`Admin > Advanced settings` - * Enable the :guilabel:`Build pull requests for this project` option - - .. tab:: |com_brand| - - This feature is enabled by a feature flag currently in testing. - You can reach our support at support@readthedocs.com to ask for it to be enabled. - - Once it is enabled you can turn it off and on by: - - * Go to :guilabel:`Admin > Advanced settings` - * Enable the :guilabel:`Build pull requests for this project` option - -Features --------- - -- **Build on Pull/Merge Request Event:** We create an external version and trigger a build for that version - when we receive pull/merge request open event from the webhook. - We also trigger a new build when a new commit has been pushed to the Pull/Merge Request. - -- **Warning Banner for Pull/Merge Request Documentation:** While building documentation for pull/merge requests - we add a warning banner at the top of those documentations to let the users know that - this documentation was generated from pull/merge requests and is not the main documentation for the project. - -- **Send Build Status Notification:** We send build status reports to the status API of the provider (e.g. GitHub, GitLab). - When a build is triggered for a pull/merge request we send build pending notification with the build URL - and after the build has finished we send success notification if the build succeeded without any error - or failure notification if the build failed. - -.. figure:: ../_static/images/guides/github-build-status-reporting.gif - :align: center - :alt: GitHub Build Status Reporting for Pull Requests. - :figwidth: 80% - :target: ../_static/images/guides/github-build-status-reporting.gif - - GitHub Build Status Reporting for Pull Requests - -Limitations ------------ - -Auto-builds for pull/merge requests have -:doc:`the same limitations as regular documentation builds `. - -Currently we don't index search for pull request builds. -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/merge request has been closed or merged. - -Troubleshooting ---------------- - -After the feature is enabled on your project, -you might hit one of these issues: - -#. **Pull Requests builds are not triggering**. - We only support GitHub and GitLab currently. You need to make sure - that your Read the Docs account is connected with that providers social account. - You can check this by going to your `profile settings`_. - -#. **Build status is not being reported on your Pull/Merge Request**. - You need to make sure that you have granted access to the Read the Docs - `OAuth App`_ to your/organizations GitHub account. If you do not see "Read the Docs" - among the `OAuth App`_, you might need to disconnect and reconnect to GitHub service. - Also make sure your webhook is properly setup - to handle events. You can setup or ``re-sync`` the webhook from your projects admin dashboard. - Learn more about setting up webhooks from our :doc:`Webhook Documentation `. - -If you have tried all the above troubleshooting and still getting issues, -please let us know by sending us an `email `__. - -.. _profile settings: https://readthedocs.org/accounts/social/connections/ -.. _OAuth App: https://github.com/settings/applications diff --git a/docs/guides/build-notifications.rst b/docs/guides/build-notifications.rst index bf2d194ccc7..83fff17fd52 100644 --- a/docs/guides/build-notifications.rst +++ b/docs/guides/build-notifications.rst @@ -4,7 +4,7 @@ Enabling Build Notifications .. note:: Currently we don't send notifications when - a :doc:`build from a pull/merge request fails `. + a :doc:`build from a pull/merge request fails `. Using email ----------- diff --git a/docs/guides/platform.rst b/docs/guides/platform.rst index 07f7d5b9e13..d51d7af6e17 100644 --- a/docs/guides/platform.rst +++ b/docs/guides/platform.rst @@ -6,7 +6,6 @@ These guides will help you customize or tune aspects of Read the Docs. .. toctree:: :maxdepth: 1 - autobuild-docs-for-pull-requests build-notifications build-using-too-many-resources canonical diff --git a/docs/index.rst b/docs/index.rst index 10140ba7601..66b3e350a1f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -76,7 +76,8 @@ and some of the core features of Read the Docs. :doc:`/versions` | :doc:`/downloadable-documentation` | :doc:`/hosting` | - :doc:`/server-side-search` + :doc:`/server-side-search` | + :doc:`/pull-requests` * **Connecting with GitHub, BitBucket, or GitLab**: :doc:`Connecting your VCS account ` | @@ -102,6 +103,7 @@ and some of the core features of Read the Docs. /versions /downloadable-documentation /server-side-search + /pull-requests /hosting /connected-accounts diff --git a/docs/pull-requests.rst b/docs/pull-requests.rst new file mode 100644 index 00000000000..5bb89d2a4e6 --- /dev/null +++ b/docs/pull-requests.rst @@ -0,0 +1,73 @@ +Preview Documentation from Pull Requests +======================================== + +Read the Docs allows to build and preview your documentation from pull/merge requests. +You can enable it by: + +#. Go to your project dashboard +#. Go to :guilabel:`Admin > Advanced settings` +#. Enable the :guilabel:`Build pull requests for this project` option +#. Click on :guilabel:`Save` + +Features +-------- + +- **Build on Pull/Merge Request Events:** We create and build a new version when a pull/merge request is open, + and when a new commit has been pushed. + +- **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:: This feature is available only for :doc:`Sphinx projects `. + +- **Build Status Report:** When a build is triggered, a build pending notification is send with a link to the build log, + 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. + +.. figure:: /_static/images/github-build-status-reporting.gif + :align: center + :alt: GitHub Build Status Reporting for Pull Requests. + :figwidth: 80% + :target: ../_static/images/guides/github-build-status-reporting.gif + + GitHub build status reporting + +Privacy levels +-------------- + +.. note:: + + Privacy levels are only supported on :doc:`/commercial/index`. + +All docs built from a pull/merge requests are private by default. +Currently, this can't be changed, but we are planning to support this. + +Limitations +----------- + +- Auto-builds for pull/merge requests have + :doc:`the same limitations as regular documentation builds `. +- Only available for GitHub and GitLab. +- Additional formats like PDF and Epub aren't build. +- 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/merge request has been closed or merged. + +Troubleshooting +--------------- + +#. **Pull Requests builds are not triggering**. + We only support GitHub and GitLab currently. You need to make sure + that your Read the Docs account is connected with that providers social account. + You can check this by going to your `profile settings`_. + +#. **Build status is not being reported on your Pull/Merge Request**. + You need to make sure that you have granted access to the Read the Docs + `OAuth App`_ to your/organizations GitHub account. If you do not see "Read the Docs" + among the `OAuth App`_, you might need to disconnect and reconnect to GitHub service. + Also make sure your webhook is properly setup + to handle events. You can setup or ``re-sync`` the webhook from your projects admin dashboard. + Learn more about setting up webhooks from our :doc:`Webhook Documentation `. + +.. _profile settings: https://readthedocs.org/accounts/social/connections/ +.. _OAuth App: https://github.com/settings/applications From 3182d83d183a7405c485bad537cd87b9c5a545b5 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Wed, 13 Jan 2021 11:44:50 -0500 Subject: [PATCH 2/5] Apply suggestions from code review Co-authored-by: Eric Holscher <25510+ericholscher@users.noreply.github.com> --- docs/pull-requests.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/pull-requests.rst b/docs/pull-requests.rst index 5bb89d2a4e6..e3bb634ac19 100644 --- a/docs/pull-requests.rst +++ b/docs/pull-requests.rst @@ -1,8 +1,8 @@ Preview Documentation from Pull Requests ======================================== -Read the Docs allows to build and preview your documentation from pull/merge requests. -You can enable it by: +Read the Docs allows you to build and preview your documentation from pull/merge requests. +To enable this feature: #. Go to your project dashboard #. Go to :guilabel:`Admin > Advanced settings` @@ -20,8 +20,8 @@ Features .. note:: This feature is available only for :doc:`Sphinx projects `. -- **Build Status Report:** When a build is triggered, a build pending notification is send with a link to the build log, - 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. +- **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. .. figure:: /_static/images/github-build-status-reporting.gif :align: center @@ -47,7 +47,7 @@ Limitations - Auto-builds for pull/merge requests have :doc:`the same limitations as regular documentation builds `. - Only available for GitHub and GitLab. -- Additional formats like PDF and Epub aren't build. +- 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. @@ -61,12 +61,12 @@ Troubleshooting that your Read the Docs account is connected with that providers social account. You can check this by going to your `profile settings`_. -#. **Build status is not being reported on your Pull/Merge Request**. +#. **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/organizations GitHub account. If you do not see "Read the Docs" - among the `OAuth App`_, you might need to disconnect and reconnect to GitHub service. + `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. You can setup or ``re-sync`` the webhook from your projects admin dashboard. + 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 :doc:`Webhook Documentation `. .. _profile settings: https://readthedocs.org/accounts/social/connections/ From 74df71db645222926659c265c33b9abf577a9972 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Wed, 13 Jan 2021 11:53:33 -0500 Subject: [PATCH 3/5] Suggestions from review --- docs/pull-requests.rst | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/pull-requests.rst b/docs/pull-requests.rst index e3bb634ac19..9e57205e4de 100644 --- a/docs/pull-requests.rst +++ b/docs/pull-requests.rst @@ -1,8 +1,8 @@ Preview Documentation from Pull Requests ======================================== -Read the Docs allows you to build and preview your documentation from pull/merge requests. -To enable this feature: +Read the Docs allows you to build and preview your documentation from pull requests. +To enable this feature: #. Go to your project dashboard #. Go to :guilabel:`Admin > Advanced settings` @@ -12,17 +12,17 @@ To enable this feature: Features -------- -- **Build on Pull/Merge Request Events:** We create and build a new version when a pull/merge request is open, +- **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:: This feature is available only for :doc:`Sphinx projects `. -- **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. - .. figure:: /_static/images/github-build-status-reporting.gif :align: center :alt: GitHub Build Status Reporting for Pull Requests. @@ -38,20 +38,20 @@ Privacy levels Privacy levels are only supported on :doc:`/commercial/index`. -All docs built from a pull/merge requests are private by default. +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 ----------- -- Auto-builds for pull/merge requests have - :doc:`the same limitations as regular documentation builds `. +- Builds from pull requests have the same memory and time limitations + :doc:`as regular builds `. - Only available for GitHub and GitLab. -- Additional formats like PDF and Epub aren't built to produce results quicker. +- 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/merge request has been closed or merged. +- The built documentation is kept for 90 days after the pull request has been closed or merged. Troubleshooting --------------- From 6f8f4963ac6a5e9a6f7eb2e182f05dc7e3d49d48 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Wed, 13 Jan 2021 15:37:40 -0500 Subject: [PATCH 4/5] Improve wording --- docs/pull-requests.rst | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/pull-requests.rst b/docs/pull-requests.rst index 9e57205e4de..def8dcd6707 100644 --- a/docs/pull-requests.rst +++ b/docs/pull-requests.rst @@ -56,15 +56,17 @@ Limitations Troubleshooting --------------- -#. **Pull Requests builds are not triggering**. - We only support GitHub and GitLab currently. You need to make sure - that your Read the Docs account is connected with that providers social account. +#. **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`_. #. **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. + `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 :doc:`Webhook Documentation `. From 28eb265606e78637a026074b3b948662b8c6bf22 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Tue, 26 Jan 2021 15:41:41 -0500 Subject: [PATCH 5/5] Apply suggestions from code review Co-authored-by: Eric Holscher <25510+ericholscher@users.noreply.github.com> --- docs/guides/build-notifications.rst | 2 +- docs/pull-requests.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/build-notifications.rst b/docs/guides/build-notifications.rst index 83fff17fd52..d57b726c12a 100644 --- a/docs/guides/build-notifications.rst +++ b/docs/guides/build-notifications.rst @@ -4,7 +4,7 @@ Enabling Build Notifications .. note:: Currently we don't send notifications when - a :doc:`build from a pull/merge request fails `. + a :doc:`build from a pull request fails `. Using email ----------- diff --git a/docs/pull-requests.rst b/docs/pull-requests.rst index def8dcd6707..b9798e26cbb 100644 --- a/docs/pull-requests.rst +++ b/docs/pull-requests.rst @@ -21,7 +21,7 @@ Features - **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:: This feature is available only for :doc:`Sphinx projects `. + .. note:: Warning banners are available only for :doc:`Sphinx projects `. .. figure:: /_static/images/github-build-status-reporting.gif :align: center