Work with Read the Docs, then you'll find that PR for documentation needs additional steps like:

• running RTD build for your branch manually, to use its result as staging site like this, or
• sharing screenshot to share the updated document like this.

This GitHub Action automates the first approach; activate RTD build automatically when you made PR that updates the document.

From v2, this system only works as a GitHub Action. v1 worked as a service (GitHub Probot) too.

0. Make sure that your RTD project has been connected with GitHub repository, or integrated via GitHub webhook.
1. Add a step to your GitHub Actions workflow. Here is a sample .github/workflows/build.yml:

name: Documentation
on:
  pull_request_target:
    paths:
      - "docs/**"
    types:
      - opened
      - reopened
      - synchronize
      - closed # necessary to deactivate the version in Read the Docs
permissions:
  pull-requests: write
  checks: write
jobs:
  staging:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to the staging site
        uses: KengoTODA/readthedocs-action@main
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          rtd-token: ${{ secrets.RTD_TOKEN }}
          rtd-project: your-read-the-docs-project

Here secrets.RTD_TOKEN is the token issued by Read the Docs. See official doc for detail.

If you use translations feature, make sure you've configured all your RTD projects including translations.

Set the project slug of the root RTD project to project config.

1. Uninstall the GitHub App from your repository.
2. Remove the.github/config.yml file that is no longer needed.
3. Set one GitHub Secrets RTD_TOKEN, and
4. Create a GitHub Actions workflow file to run the Action.

From 2021 Feb, Read the Docs officially provides the Pull Request Builders.

Copyright © 2018-2021 Kengo TODA

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

The RTD Helper's avatar is designed by MAM2.