Help us understand the problem. What is going on with this article?

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をダウンロードしてビルドして実行します。
    • この部分はadrdoxddox, 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://shoo.github.io/gendoc

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

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

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

image.png

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

image.png

Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Comments
No comments
Sign up for free and join this conversation.
If you already have a Qiita account
Why do not you register as a user and use Qiita more conveniently?
You need to log in to use this function. Qiita can be used more conveniently after logging in.
You seem to be reading articles frequently this month. Qiita can be used more conveniently after logging in.
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
ユーザーは見つかりませんでした