readthedocs · benjaoming · Dec 9, 2022 · Oct 19, 2022 · Oct 21, 2022 · Dec 9, 2022
diff --git a/docs/user/guides/administrators.rst b/docs/user/guides/administrators.rst
@@ -21,3 +21,4 @@ have a look at our :doc:`/tutorial/index`.
    pdf-non-ascii-languages
    importing-private-repositories
    Setup Build Notifications <build-notifications>
+   Configure Pull Request Builds <pull-requests>
diff --git a/docs/user/guides/pull-requests.rst b/docs/user/guides/pull-requests.rst
@@ -0,0 +1,80 @@
+How To Configure Pull Request Builds
+====================================
+
+In this section, you can learn how to configure :doc:`Pull Request builds </pull-requests>`.
+
+To enable Pull Request Builds 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.
+
+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
+--------------
+
+.. note::
+
+   Privacy levels are only supported on :doc:`/commercial/index`.
+
+By default, all docs built from pull requests are private.
+To change their privacy level:
+
+#. Go to your project dashboard
+#. 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 :ref:`normal versions <versions:privacy levels>`.
+
+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 </builds>`.
+- 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.
+
+Troubleshooting
+---------------
+
+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.
+
+   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`.
+
+
+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
+   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.
+
+.. seealso::
+   - :ref:`integrations:Debugging webhooks`
+   - :ref:`github-permission-troubleshooting`
+
+.. _OAuth App: https://github.com/settings/applications
diff --git a/docs/user/index.rst b/docs/user/index.rst
@@ -78,6 +78,7 @@ to help you create fantastic documentation for your project.
    /choosing-a-site
    /build-notifications
    /custom-domains
+   /pull-requests
    /downloadable-documentation
 
 
@@ -149,7 +150,6 @@ and some of the core features of Read the Docs.
    /hosting
    /server-side-search/index
    /analytics
-   /pull-requests
    /security-log
 
    /connected-accounts
@@ -183,6 +183,7 @@ and how to write successful documentation.
   :doc:`/guides/manage-translations-sphinx` |
   :doc:`/guides/private-submodules` |
   Setup Build Notifications <build-notifications> |
+  :doc:`Configure Pull Request Builds </guides/pull-requests>` |
   :doc:`More guides for administrators </guides/administrators>`
 
 * **For developers and designers**:

diff --git a/docs/user/pull-requests.rst b/docs/user/pull-requests.rst
@@ -31,81 +31,7 @@ Warning banner
 
     .. note:: Warning banners are available only for :doc:`Sphinx projects </intro/getting-started-with-sphinx>`.
 
-Configuration
--------------
-
-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.
-
-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
---------------
-
-.. note::
-
-   Privacy levels are only supported on :doc:`/commercial/index`.
-
-By default, all docs built from pull requests are private.
-To change their privacy level:
-
-#. Go to your project dashboard
-#. 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 :ref:`normal versions <versions:privacy levels>`.
-
-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 </builds>`.
-- 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.
-
-Troubleshooting
----------------
-
-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.
-
-   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`.
-
-
-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
-   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.
-
 .. seealso::
-   - :ref:`integrations:Debugging webhooks`
-   - :ref:`github-permission-troubleshooting`
 
-.. _OAuth App: https://github.com/settings/applications
+    :doc:`/guides/pull-requests`
+        A guide to configuring pull request builds on Read the Docs.