Learn about our RFC process, Open RFC meetings & more.Join in the discussion! »

rtd-bot

1.0.3 • Public • Published

Get URL of staging document, when you review changes.

Commitizen friendly semantic-release

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 bot automates the first approach; activate RTD build automatically when you made PR that updates docs/ directory.

screenshot

How to use

You have three ways to use this service:

  1. Use as a SaaS
  2. Use as a step in GitHub Action
  3. Host own service

Initial setup

No matter which way you choose, follow the following interactions:

  1. Make sure that your RTD project has been connected with GitHub repository, or integrated via GitHub webhook.
  2. Add rtd.project config to the .github/config.yml file in your repo.

Here is a sample .github/config.yml:

rtd:
  project: your-read-the-docs-project

1. Use as a SaaS

In Read the Docs, inviting maintainer means you give admin access to target account. So if you do not want to invite rtd-bot as maintainer, use other way instead of this way.

To enable rtd-bot SaaS for your GitHub repository, follow the following interactions:

  1. Invite rtd-bot user to your RTD project as maintainer.
  2. Enable rtd-bot in your repo from the rtd-bot page at GitHub.

2. Use as a step in GitHub Action (Not ready yet)

You need to set two environment variables: RTD_TOKEN and GITHUB_TOKEN. See the next section for detail.

on:
  [pull_request]
...
steps:
  ...
  - name: Build staging document
    uses: KengoTODA/rtd-bot@v1.0.3
    env:
      RTD_TOKEN: ${{ secrets.RTD_TOKEN }}
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

3. Host own service

To host this bot by own, you need to set following environment variables:

  1. RTD_TOKEN, the token issued by Read the Docs. See official doc for detail.
  2. WEBHOOK_SECRET and APP_ID that is described at Probot document.
  3. One of PRIVATE_KEY_PATH or PRIVATE_KEY that is described at Probot document.

Advanced Configuration

Configuration for the project with translations

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

In .github/config.yml file, set the project slug of the root RTD project.

License

Copyright © 2018-2020 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.

Install

npm i rtd-bot

DownloadsWeekly Downloads

3

Version

1.0.3

License

Apache-2.0

Unpacked Size

43.6 kB

Total Files

14

Last publish

Collaborators

  • avatar