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.
- Make sure that your RTD project has been connected with GitHub repository, or integrated via GitHub webhook.
- 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.
- Uninstall the GitHub App from your repository.
- Remove the
.github/config.yml
file that is no longer needed. - Set one GitHub Secrets
RTD_TOKEN
, and - Create a GitHub Actions workflow file to run the Action.
- Stop inviting the
rtd-bot
RTD account as maintainer.
From 2021 Feb, Read the Docs officially provides the Pull Request Builders.
Copyright Β© 2018-2022 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.