D言語+Travis-CIでドキュメントのデプロイ自動化する話

概要

D言語でもTravis-CIやCircle-CIをはじめとする各種CIサービスでテスト・デプロイが可能です。
今回はTravis-CIを用いてドキュメント生成を自動化するテンプレを紹介します。
過去記事とは別の方法でテスト設定を記述します。
ちなみにドキュメント生成にはdub+gendocを使う前提です。

1. D言語＋Travis-CIでテスト自動化する話➀
2. D言語＋Travis-CIでテスト自動化する話②
3. D言語＋Travis-CIでリリースのデプロイ自動化する話
4. D言語+Travis-CIでドキュメントのデプロイ自動化する話 ← この記事

.travis.yml のテンプレ

.travis.yml

language: d

script: ./.travis.sh
sudo: false

jobs:
  include:
    # =============================== Test Stage ===============================
    # ここにテスト設定を記載
    
    # ========================== Documentation Stage ===========================
    - stage: Documentation
      d: ldc
      os: linux
      script:
        - echo "Deploying to GitHub pages ..." && dub run gendoc -y
      deploy:
        - provider: pages
          skip_cleanup: true
          local_dir: docs
          github_token: $GH_REPO_TOKEN
          on:
            tags: false
            branch: master

    # ========================== GitHub Release Stage ==========================
    # ここにGitHubリリースのデプロイ設定を記載

stages:
  - name: test
    if: type = pull_request or (type = push and branch = master)
  - name: Documentation
    if: type = push and branch = master

解説

• $GH_REPO_TOKEN はデプロイに必要なトークン。
  GitHubにて、ユーザーアカウントの「Settings」→「Developer settings」→「Personal access tokens」へとたどり発行できます。権限はSelect scopesで設定し、「repo_deployment / Access deployment status」をチェックします。
  このキーをTravis-CIの各リポジトリの設定で「more options」→「Environment Variables」の欄に登録します。
• dub run gendoc -y としている部分がドキュメントを生成する部分。gendocをダウンロードしてビルドして実行します。
  • この部分はadrdoxやddox, harbored-mod でもいいでしょう。CanDyDocがいい場合は dub run gendoc:candydoc でドキュメントを生成できます。
• 上記テンプレの設定の場合、masterにpushするたびに毎回ドキュメント生成は行ってデプロイする設定になる。
  • 最新版(最後につけたタグ)より新しいドキュメントが公開されることになるので注意。
  • 最新版のドキュメントだけにしたい場合はtags:trueにしたうえで、タグが付けられた時にもドキュメント生成を行うようにif: ...を消すか、タグの条件も追加すること。
• 毎回ドキュメント生成したくない場合 → TravisCI タグをプッシュした時だけ動くビルドステージの設定 By @masakurapa

生成結果を閲覧する

生成結果はTravis-CIのボットによって gh_pages ブランチにコミットされます。
GitHubの対象リポジトリの「Settings」→「GitHub Pages」→「Source」を「gh_pages branch」に変更します。

といった感じに
https://<アカウント名>.github.io/<リポジトリ名>
のアドレスでアクセスできるようになります。
README.md にもリンクを張り付けておくといいかもしれません。

さらに、そのプロジェクトを自身がdubパッケージとして登録している場合、以下のようなプロジェクトの概要ページの「Documentation」の表示先も変更することができます。
https://code.dlang.org/packages/gendoc

https://code.dlang.org にアクセスして、「Log in」します。その後、プロジェクトのページ右側に「Manage this Package」のボタンが出現するので、クリックします。

その後、以下のように表示される「General」のタブのページで「Documentation URL」に先ほどのURLを入力することで、Documentationタブのリンク先のページが変更されます。