Kengo's blog

Technical articles about original projects, JVM, Static Analysis and TypeScript.

Read The Docs利用者用にPRレビュー支援Probotを作りました

私がSpotBugsなどで使っているドキュメントホスティングサービス、Read The Docsを使う上で助けになるGitHub Probotを作成しました。

github.com

ドキュメントがいつもどおり全部英語なので、日本語での解説をここに書いておきます。

想定ユーザ

  • Read The Docsを使ったドキュメント作成を複数人で行っている
  • Read The Docsの設定をあまりいじっていない

解決する問題

  • Read The Docsが単体でPRレビュー用ビルドを提供していないので、レビューしてもらう時にステージングサイトやスクリーンショットを主導で用意しなければならない。

解決手法

  • PR作成時に docs ディレクトリに変更が入っていれば、Read The Docs上でのビルドとホスティングを有効化し、アクセス用URLをPRに書き込む。

インストール方法

  1. Read The DocsプロジェクトをGitHubリポジトリと接続しておく、あるいはGitHub Webhookと統合しておく
  2. Read The Docsプロジェクトに rtd-bot ユーザをメンテナーとして招待しておく。
  3. Gitリポジトリ.github/config.ymlrtd.project を作成し、Read The Docsプロジェクト名とその言語を指定する
  4. GitHub上でrtd-botを有効化する

注意点

  • いまのところ、Read The Docs側の設定項目(例えばドキュメントの場所など)には柔軟に追従できません。
  • 現バージョンのRead The Docsにおける「メンテナーの招待」は、「全権限の委譲」にほかなりません。不安な場合はご自身でProbotをホストいただけます。

技術的な工夫と、今後の開発の予定

このプロジェクトではCommitizenSemantic Releaseを導入しました。思っていたよりも使いやすく、またDependabotがすでにcommitizen風コミットコメントに対応していたため、特に導入に障害はありませんでした。MavenやGradleでも使えたら良いんですが、そこはまだハックが必要そうです。

Read The DocsのAPIはまだ機能不足が目立ちます。最近出たAPI v2でも認証機能すら無く、公開データへの読み取りアクセスしかできません。 今回はこの問題の回避にPuppeteerを使っています。つまり管理画面をNode.jsで操作しています。だいぶダーティハックですが、利用規約上も問題ないはずです。画面の更新には逐次追随する必要がありますが、過去の経験から言ってRead The Docsの画面はさほど大きく変更が入らないと思われます。

直近の予定としては、i18nには対応したいと考えています。他にも対応必要な設定があればROADMAP.mdに追記のPRを送ってください。