kengotoda / readthedocs-action

An unofficial GitHub Probot that helps reviewing on Read the Docs

Get the staging document in PR

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.

How to use

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

Initial setup

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.

Advanced Configuration

Configuration for the project with translations

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.

Migrating from v1 to v2

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.
5. Stop inviting the rtd-bot RTD account as maintainer.

Alternative Solutions

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

License

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.

readthedocs-action's Issues

TODO

• add Test with tokens to the branch protection rule by LouisBrunner/checks-action
• make sure that the ref in PR was used to checkout the code

404 caused if branch name contains upper case chars

https://github.com/spotbugs/spotbugs/runs/3530663018#step:2:6

UnhandledPromiseRejectionWarning: Error: Unexpected status code 404 with body: {"detail":"Not found."}
at /home/runner/work/_actions/KengoTODA/readthedocs-action/main/webpack:/rtd-bot/src/rtd.ts:141:1
at processTicksAndRejections (internal/process/task_queues.js:93:5)

it seems that RTD server requires lower case, because the URL of version on the site is like https://readthedocs.org/dashboard/spotbugs/version/kengotoda-patch-1/edit/
even when the branch is named as KengoTODA-patch-1.

The automated release is failing 🚨

🚨 The automated release from the master branch failed. 🚨

I recommend you give this issue a high priority, so other packages depending on you could benefit from your bug fixes and new features.

You can find below the list of errors reported by semantic-release. Each one of them has to be resolved in order to automatically publish your package. I’m sure you can resolve this 💪.

Errors are usually caused by a misconfiguration or an authentication problem. With each error reported below you will find explanation and guidance to help you to resolve it.

Once all the errors are resolved, semantic-release will release your package the next time you push a commit to the master branch. You can also manually restart the failed CI job that runs semantic-release.

If you are not sure how to resolve this, here is some links that can help you:

• Usage documentation
• Frequently Asked Questions
• Support channels

If those don’t help, or if this issue is reporting something you think isn’t right, you can always ask the humans behind semantic-release.

---

No npm token specified.

An npm token must be created and set in the NPM_TOKEN environment variable on your CI environment.

Please make sure to create an npm token and to set it in the NPM_TOKEN environment variable on your CI environment. The token must allow to publish to the registry https://registry.npmjs.org/.

---

Good luck with your project ✨

Your semantic-release bot 📦🚀

TypeError: Cannot read property 'full_name' of null

When given event is event: pull_request.closed. we face TypeError in index.js because pull_request.base.repo or pull_request.head.repo is null. This problem was caused at https://github.com/KengoTODA/rtd-bot/blob/64e800cd68334e8e385035c6fb2f10aafe46deab/src/index.ts#L36

Sentry URL: https://sentry.io/kengotoda/rtd-helper/issues/680874511/?query=is:unresolved

📣 The rtd-bot v1 will be offline due to Heroku's policy change

Today Heroku announced that the free plans will end this November:

Starting November 28, 2022, we plan to stop offering free product plans and plan to start shutting down free dynos and data services. We will be sending out a series of email communications to affected users.

rtd-bot v1 is running on a Heroku free dyno. So for all of v1 users, I suggest to:

1. Migrate from v1 to v2. The v2 is implemented as GitHub Action so you can use your own API token to control your documents, or
2. Use the official PR integration feature instead.

Stop depending on Deprecated APIs

Log in production contains the following deprecation warning:

2020-03-09T13:01:07.664545+00:00 app[web.1]: Deprecation: [@octokit/rest] Setting the "new Octokit({ auth })" option to an object without also setting the "authStrategy" option is deprecated and will be removed in v17. See (https://octokit.github.io/rest.js/#authentication)

Bot report issues even after PR is closed

spotbugs/spotbugs#847

pull_request.body could be null

Cannot read property 'indexOf' of null

readthedocs-action/src/build_body.ts

Line 12 in e16301c

if (existingBody.indexOf(START) >= 0) {

Event reported by Sentry

https://sentry.io/share/issue/1a4f7dd980a64a729797a31a93b02617/

Replace pupetteer

To support GitHub Actions, we need to reduce file size of project including node_modules (or use LFS).
If RTD provides enough WebAPI, use it instead.

Error: spawn /app/node_modules/puppeteer/.local-chromium/linux-609904/chrome-linux/chrome EAGAIN

Sometimes we fail to launch chrome on Heroku, the production environment. Still not sure how to resolve this error.

{
  code: EAGAIN, 
  errno: EAGAIN, 
  path: /app/node_modules/puppeteer/.local-chromium/linux-609904/chrome-linux/chrome, 
  spawnargs: [
    --disable-background-networking, 
    --disable-background-timer-throttling, 
    --disable-backgrounding-occluded-windows, 
    --disable-breakpad, 
    --disable-client-side-phishing-detection, 
    --disable-default-apps, 
    --disable-dev-shm-usage, 
    --disable-extensions, 
    --disable-features=site-per-process, 
    --disable-hang-monitor, 
    --disable-ipc-flooding-protection, 
    --disable-popup-blocking, 
    --disable-prompt-on-repost, 
    --disable-renderer-backgrounding, 
    --disable-sync, 
    --disable-translate, 
    --metrics-recording-only, 
    --no-first-run, 
    --safebrowsing-disable-auto-update, 
    --enable-automation, 
    [Filtered], 
    --use-mock-keychain, 
    --headless, 
    --hide-scrollbars, 
    --mute-audio, 
    about:blank, 
    --no-sandbox, 
    --remote-debugging-port=0, 
    --user-data-dir=/tmp/puppeteer_dev_profile-dmPe96
  ], 
  syscall: spawn /app/node_modules/puppeteer/.local-chromium/linux-609904/chrome-linux/chrome
}

Add on option to disable rtd-bot in config.yml

The motivation is that I'm having GitHub App integration enabled for the whole org.
But I want to prevent bot spamming with config reminders to irrelevant repos. Like a repo with gh-pages hosted static website.

Add this product to https://www.kengo-toda.jp/

existingBody can be null

Trigger a build after enable it

Currently it is necessary to trigger a build by https://docs.readthedocs.io/en/stable/api/v3.html#build-triggering
Not sure when behavior of RTD has been changed, tho.

Report build error/warning to PR

The reviewer may want to confirm that the build process reported which kind of error/warning.
To support this demand, it's nice to report error/warning logs to the target PR.

Bot is still working even after PR is merged

We face this issue even after we release #107 to production. Example:

• pypa/virtualenv#1292

This issue triggers error message like "Failed to visit version page".

RTD do not build pull requests

Hi, first of all, very good job 👍

I wanted to notify you that it's around a week that we don't see any comment for the build.
This is a sample pull request that didn't triggered it :
geosolutions-it/MapStore2#3868

Hope it helps

Explain necessary config in Probot side

This probot needs permission to read/write PR, and read .github/config.yml. For who hosts rtd-bot by own, explain these information in README.md.