From 7d5f83d9b8cd2d5d32464f64bea09d793421713b Mon Sep 17 00:00:00 2001 From: Anthony Johnson Date: Mon, 9 May 2022 16:22:30 -0700 Subject: [PATCH 1/3] Spruce up docs on pull request builds I keep helping users with the support request around webhooks missing the pull request event, so wanted to clarify a bit here. I also took the opportunity to add some clearer language to the rest of the page, and resturcture a few things to improve the information flow. I also opened #9176 to deal with this in a programmatic way, but figured we could at least communicate the issue better for now. --- docs/user/pull-requests.rst | 95 +++++++++++++++++++++++-------------- 1 file changed, 60 insertions(+), 35 deletions(-) diff --git a/docs/user/pull-requests.rst b/docs/user/pull-requests.rst index 7fd6243389c..aa77c2c7d36 100644 --- a/docs/user/pull-requests.rst +++ b/docs/user/pull-requests.rst @@ -1,37 +1,49 @@ Preview Documentation from Pull Requests ======================================== -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` -#. Enable the :guilabel:`Build pull requests for this project` option -#. Click on :guilabel:`Save` +Your project can be configured to build and host documentation for every new +pull request. Previewing changes to your documentation during review makes it +easier to catch documentation formatting and display issues introduced in pull +requests. 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. + We create and build a new version when a pull request is opened, + and rebuild the version whenever a new commit is 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. + Your project's pull request build status will show as as one of your pull + request's checks. This status will update as the build is running, and will + show a success or failure status when the build completes. + + .. figure:: /_static/images/github-build-status-reporting.gif + :align: center + :alt: GitHub build status reporting for pull requests. + :figwidth: 80% + + GitHub build status reporting 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. + A warning banner is shown at the top of documentation pages + to let readers know that this version isn't the main version for the project. + + .. note:: Warning banners are available only for :doc:`Sphinx projects `. - .. note:: Warning banners are available only for :doc:`Sphinx projects `. +Configuration +------------- -.. figure:: /_static/images/github-build-status-reporting.gif - :align: center - :alt: GitHub build status reporting for pull requests. - :figwidth: 80% +To enable this feature for your project, +your Read the Docs account needs to be connected to an account with a supported VCS provider. +See `Limitations`_ for more information. - GitHub build status reporting +If your account is already connected: + +#. Go to your project dashboard +#. Go to :guilabel:`Admin`, then :guilabel:`Advanced settings` +#. Enable the :guilabel:`Build pull requests for this project` option +#. Click on :guilabel:`Save` Privacy levels -------------- @@ -40,24 +52,26 @@ Privacy levels Privacy levels are only supported on :doc:`/commercial/index`. -By default all docs built from pull requests are private. +By default, all docs built from pull requests are private. To change their privacy level: #. Go to your project dashboard -#. Go to :guilabel:`Admin > Advanced settings` +#. Go to :guilabel:`Admin`, then :guilabel:`Advanced settings` #. Select your option in :guilabel:`Privacy level of builds from pull requests` #. Click on :guilabel:`Save` -Privacy levels work the same way as for :ref:`normal versions `. +Privacy levels work the same way as :ref:`normal versions `. Limitations ----------- +- Only available for **GitHub** and **GitLab** currently. Bitbucket is not yet supported. +- To enable this feature, your Read the Docs account needs to be connected to an + account with your VCS provider. - 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. -- Searches will default to the default experience for your tool. +- Additional formats like PDF and EPUB aren't built, to reduce build time. +- Search queries 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. @@ -65,18 +79,29 @@ Limitations Troubleshooting --------------- -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 :guilabel:`Username dropdown` > :guilabel:`Settings` > :guilabel:`Connected Services`. +No new builds are started when I open a pull request + The most common cause is that your repository's webhook is not configured to + send Read the Docs pull request events. You'll need to re-sync your project's + webhook integration to reconfigure the Read the Docs webhook. + + You may also notice this behavior if your Read the Docs account is not + connected to your VCS provider account, or if it needs to be reconnected. + You can (re)connect your account by going to your :guilabel:`Username dropdown`, + :guilabel:`Settings`, then to :guilabel:`Connected Services`. + + .. seealso:: + :ref:`integrations:Debugging webhooks` 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. - Learn more about this in our :ref:`github-permission-troubleshooting` section. + If opening a pull request does start a new build, but the build status is not + being updated with your VCS provider, then your connected account may have out + dated or insufficient permisisons. + + Make sure that you have granted access to the Read the Docs `OAuth App`_ for + your personal or organization GitHub account. You can also try reconnecting + your account with your VCS provider. - Also make sure your webhook integration is properly setup - to handle events related to pull requests. You can setup or ``re-sync`` the integration from your projects admin dashboard. - Learn more about setting up integrations from our :doc:`integrations documentation `. + .. seealso:: + :ref:`github-permission-troubleshooting` .. _OAuth App: https://github.com/settings/applications From 84e92b8773e82d978215618815d45faffadcb921 Mon Sep 17 00:00:00 2001 From: Anthony Date: Mon, 9 May 2022 17:35:57 -0600 Subject: [PATCH 2/3] Update docs/user/pull-requests.rst Co-authored-by: Santos Gallegos --- docs/user/pull-requests.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/pull-requests.rst b/docs/user/pull-requests.rst index aa77c2c7d36..8349b3517ac 100644 --- a/docs/user/pull-requests.rst +++ b/docs/user/pull-requests.rst @@ -14,7 +14,7 @@ Build on pull request events and rebuild the version whenever a new commit is pushed. Build status report - Your project's pull request build status will show as as one of your pull + Your project's pull request build status will show as one of your pull request's checks. This status will update as the build is running, and will show a success or failure status when the build completes. From e611f1268b0ef47bc23db53d33903ca90944b5f7 Mon Sep 17 00:00:00 2001 From: Anthony Johnson Date: Mon, 9 May 2022 16:46:09 -0700 Subject: [PATCH 3/3] Consolidate seealso blocks --- docs/user/pull-requests.rst | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/user/pull-requests.rst b/docs/user/pull-requests.rst index 8349b3517ac..e109e7cbdac 100644 --- a/docs/user/pull-requests.rst +++ b/docs/user/pull-requests.rst @@ -84,13 +84,16 @@ No new builds are started when I open a pull request send Read the Docs pull request events. You'll need to re-sync your project's webhook integration to reconfigure the Read the Docs webhook. + To resync your project's webhook, go to your project's admin dashboard, + :guilabel:`Integrations`, and then select the webhook integration for your + provider. Follow the directions on to re-sync the webhook, or create a new + webhook integration. + You may also notice this behavior if your Read the Docs account is not connected to your VCS provider account, or if it needs to be reconnected. You can (re)connect your account by going to your :guilabel:`Username dropdown`, :guilabel:`Settings`, then to :guilabel:`Connected Services`. - .. seealso:: - :ref:`integrations:Debugging webhooks` Build status is not being reported to your VCS provider If opening a pull request does start a new build, but the build status is not @@ -101,7 +104,8 @@ Build status is not being reported to your VCS provider your personal or organization GitHub account. You can also try reconnecting your account with your VCS provider. - .. seealso:: - :ref:`github-permission-troubleshooting` +.. seealso:: + - :ref:`integrations:Debugging webhooks` + - :ref:`github-permission-troubleshooting` .. _OAuth App: https://github.com/settings/applications