Skip to content

Commit 2f64539

Browse files
benjaomingbenjaoming
authored
Docs: Split up Pull Request Builds into a how-to guide and reference (Diátaxis) (#9679)
* Split up Pull Request Builds since it's pretty much 50:50 in reference and how-to (Diátaxis) * Reformat seealso:: box to @agjohnson's proposal * Move Pull Request Builds to Explanation menu
1 parent fb53cab commit 2f64539

File tree

4 files changed

+85
-77
lines changed

4 files changed

+85
-77
lines changed

‎docs/user/guides/administrators.rst

+1
Original file line numberDiff line numberDiff line change
@@ -21,3 +21,4 @@ have a look at our :doc:`/tutorial/index`.
2121
pdf-non-ascii-languages
2222
importing-private-repositories
2323
Setup Build Notifications <build-notifications>
24+
Configure Pull Request Builds <pull-requests>

‎docs/user/guides/pull-requests.rst

+80
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
How To Configure Pull Request Builds
2+
====================================
3+
4+
In this section, you can learn how to configure :doc:`Pull Request builds </pull-requests>`.
5+
6+
To enable Pull Request Builds for your project,
7+
your Read the Docs account needs to be connected to an account with a supported VCS provider.
8+
See `Limitations`_ for more information.
9+
10+
If your account is already connected:
11+
12+
#. Go to your project dashboard
13+
#. Go to :guilabel:`Admin`, then :guilabel:`Advanced settings`
14+
#. Enable the :guilabel:`Build pull requests for this project` option
15+
#. Click on :guilabel:`Save`
16+
17+
Privacy levels
18+
--------------
19+
20+
.. note::
21+
22+
Privacy levels are only supported on :doc:`/commercial/index`.
23+
24+
By default, all docs built from pull requests are private.
25+
To change their privacy level:
26+
27+
#. Go to your project dashboard
28+
#. Go to :guilabel:`Admin`, then :guilabel:`Advanced settings`
29+
#. Select your option in :guilabel:`Privacy level of builds from pull requests`
30+
#. Click on :guilabel:`Save`
31+
32+
Privacy levels work the same way as :ref:`normal versions <versions:privacy levels>`.
33+
34+
Limitations
35+
-----------
36+
37+
- Only available for **GitHub** and **GitLab** currently. Bitbucket is not yet supported.
38+
- To enable this feature, your Read the Docs account needs to be connected to an
39+
account with your VCS provider.
40+
- Builds from pull requests have the same memory and time limitations
41+
:doc:`as regular builds </builds>`.
42+
- Additional formats like PDF and EPUB aren't built, to reduce build time.
43+
- Search queries will default to the default experience for your tool.
44+
This is a feature we plan to add,
45+
but don't want to overwhelm our search indexes used in production.
46+
- The built documentation is kept for 90 days after the pull request has been closed or merged.
47+
48+
Troubleshooting
49+
---------------
50+
51+
No new builds are started when I open a pull request
52+
The most common cause is that your repository's webhook is not configured to
53+
send Read the Docs pull request events. You'll need to re-sync your project's
54+
webhook integration to reconfigure the Read the Docs webhook.
55+
56+
To resync your project's webhook, go to your project's admin dashboard,
57+
:guilabel:`Integrations`, and then select the webhook integration for your
58+
provider. Follow the directions on to re-sync the webhook, or create a new
59+
webhook integration.
60+
61+
You may also notice this behavior if your Read the Docs account is not
62+
connected to your VCS provider account, or if it needs to be reconnected.
63+
You can (re)connect your account by going to your :guilabel:`Username dropdown`,
64+
:guilabel:`Settings`, then to :guilabel:`Connected Services`.
65+
66+
67+
Build status is not being reported to your VCS provider
68+
If opening a pull request does start a new build, but the build status is not
69+
being updated with your VCS provider, then your connected account may have out
70+
dated or insufficient permisisons.
71+
72+
Make sure that you have granted access to the Read the Docs `OAuth App`_ for
73+
your personal or organization GitHub account. You can also try reconnecting
74+
your account with your VCS provider.
75+
76+
.. seealso::
77+
- :ref:`integrations:Debugging webhooks`
78+
- :ref:`github-permission-troubleshooting`
79+
80+
.. _OAuth App: https://github.com/settings/applications

‎docs/user/index.rst

+2-1
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,7 @@ to help you create fantastic documentation for your project.
7878
/choosing-a-site
7979
/build-notifications
8080
/custom-domains
81+
/pull-requests
8182
/downloadable-documentation
8283

8384

@@ -149,7 +150,6 @@ and some of the core features of Read the Docs.
149150
/hosting
150151
/server-side-search/index
151152
/analytics
152-
/pull-requests
153153
/security-log
154154

155155
/connected-accounts
@@ -183,6 +183,7 @@ and how to write successful documentation.
183183
:doc:`/guides/manage-translations-sphinx` |
184184
:doc:`/guides/private-submodules` |
185185
Setup Build Notifications <build-notifications> |
186+
:doc:`Configure Pull Request Builds </guides/pull-requests>` |
186187
:doc:`More guides for administrators </guides/administrators>`
187188

188189
* **For developers and designers**:

‎docs/user/pull-requests.rst

+2-76
Original file line numberDiff line numberDiff line change
@@ -31,81 +31,7 @@ Warning banner
3131

3232
.. note:: Warning banners are available only for :doc:`Sphinx projects </intro/getting-started-with-sphinx>`.
3333

34-
Configuration
35-
-------------
36-
37-
To enable this feature for your project,
38-
your Read the Docs account needs to be connected to an account with a supported VCS provider.
39-
See `Limitations`_ for more information.
40-
41-
If your account is already connected:
42-
43-
#. Go to your project dashboard
44-
#. Go to :guilabel:`Admin`, then :guilabel:`Advanced settings`
45-
#. Enable the :guilabel:`Build pull requests for this project` option
46-
#. Click on :guilabel:`Save`
47-
48-
Privacy levels
49-
--------------
50-
51-
.. note::
52-
53-
Privacy levels are only supported on :doc:`/commercial/index`.
54-
55-
By default, all docs built from pull requests are private.
56-
To change their privacy level:
57-
58-
#. Go to your project dashboard
59-
#. Go to :guilabel:`Admin`, then :guilabel:`Advanced settings`
60-
#. Select your option in :guilabel:`Privacy level of builds from pull requests`
61-
#. Click on :guilabel:`Save`
62-
63-
Privacy levels work the same way as :ref:`normal versions <versions:privacy levels>`.
64-
65-
Limitations
66-
-----------
67-
68-
- Only available for **GitHub** and **GitLab** currently. Bitbucket is not yet supported.
69-
- To enable this feature, your Read the Docs account needs to be connected to an
70-
account with your VCS provider.
71-
- Builds from pull requests have the same memory and time limitations
72-
:doc:`as regular builds </builds>`.
73-
- Additional formats like PDF and EPUB aren't built, to reduce build time.
74-
- Search queries will default to the default experience for your tool.
75-
This is a feature we plan to add,
76-
but don't want to overwhelm our search indexes used in production.
77-
- The built documentation is kept for 90 days after the pull request has been closed or merged.
78-
79-
Troubleshooting
80-
---------------
81-
82-
No new builds are started when I open a pull request
83-
The most common cause is that your repository's webhook is not configured to
84-
send Read the Docs pull request events. You'll need to re-sync your project's
85-
webhook integration to reconfigure the Read the Docs webhook.
86-
87-
To resync your project's webhook, go to your project's admin dashboard,
88-
:guilabel:`Integrations`, and then select the webhook integration for your
89-
provider. Follow the directions on to re-sync the webhook, or create a new
90-
webhook integration.
91-
92-
You may also notice this behavior if your Read the Docs account is not
93-
connected to your VCS provider account, or if it needs to be reconnected.
94-
You can (re)connect your account by going to your :guilabel:`Username dropdown`,
95-
:guilabel:`Settings`, then to :guilabel:`Connected Services`.
96-
97-
98-
Build status is not being reported to your VCS provider
99-
If opening a pull request does start a new build, but the build status is not
100-
being updated with your VCS provider, then your connected account may have out
101-
dated or insufficient permisisons.
102-
103-
Make sure that you have granted access to the Read the Docs `OAuth App`_ for
104-
your personal or organization GitHub account. You can also try reconnecting
105-
your account with your VCS provider.
106-
10734
.. seealso::
108-
- :ref:`integrations:Debugging webhooks`
109-
- :ref:`github-permission-troubleshooting`
11035

111-
.. _OAuth App: https://github.com/settings/applications
36+
:doc:`/guides/pull-requests`
37+
A guide to configuring pull request builds on Read the Docs.

0 commit comments

Comments
 (0)