Skip to content

Update docs about preview from pull/merge requests #7823

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Jan 26, 2021
Merged

Update docs about preview from pull/merge requests #7823

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
f6cbec1
Update docs about preview from pull/merge requests
stsewd Jan 13, 2021
3182d83
Apply suggestions from code review
stsewd Jan 13, 2021
74df71d
Suggestions from review
stsewd Jan 13, 2021
6f8f496
Improve wording
stsewd Jan 13, 2021
28eb265
Apply suggestions from code review
stsewd Jan 26, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
0 .../guides/github-build-status-reporting.gif → .../images/github-build-status-reporting.gif
View file
Open in desktop
File renamed without changes
86 changes: 0 additions & 86 deletions docs/guides/autobuild-docs-for-pull-requests.rst
View file
Open in desktop

This file was deleted.

2 changes: 1 addition & 1 deletion docs/guides/build-notifications.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Enabling Build Notifications
.. note::

Currently we don't send notifications when
a :doc:`build from a pull/merge request fails </guides/autobuild-docs-for-pull-requests>`.
a :doc:`build from a pull/merge request fails </pull-requests>`.

Using email
-----------
Expand Down
1 change: 0 additions & 1 deletion docs/guides/platform.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 3 additions & 1 deletion docs/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 </connected-accounts>` |
Expand All @@ -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
Expand Down
73 changes: 73 additions & 0 deletions docs/pull-requests.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 </intro/getting-started-with-sphinx>`.

- **Build Status Report:** When a build is triggered, a build pending notification is send with a link to the build log,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be above the Warning banner, it's a much bigger feature. I think we can probably just remove the warning banner section, since it's not really that useful to document?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should document it somewhere, as people some times expect this kind of fetatures to be on mkdocs projects as well. #7810

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 </builds>`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does this mean? We should clarify this, or put it at the end.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this was meant to say about the build memory/time available, I can make it more clear.

- 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this true? I thought search just didn't work :/

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It should just work, as they are regular versions, we can enable it by removing this line

readthedocs.org/readthedocs/projects/tasks.py

Lines 1318 to 1320 in 74df71d

# Don't index external version builds for now
if not version or version.type == EXTERNAL:
return

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

now with the custom options for search I think this is useful, so users can test the results.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yea, it will just destroy our search indexes. I don't want to break prod search by indexing PR's, so we probably want a different cluster for it, if nothing else.

- 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 </webhooks>`.

.. _profile settings: https://readthedocs.org/accounts/social/connections/
.. _OAuth App: https://github.com/settings/applications