なつねこメモ

主にプログラミング関連のメモ帳 ♪(✿╹ヮ╹)ﾉ

2018/09/11

GitHub + CircleCI + Netlify で自動でドキュメントの公開をしたい

カテゴリー：

Circle CI

ライブラリなどを公開する場合、ソースコード内に記述したコメントなどを元に、
自動でドキュメントを生成し、公開してくれていると非常に助かったりします。

例えば、 .NET の場合は XML ドキュメントコメントを書いてくれれば、非常に助かります。
今回は、それを master ブランチに push した際、自動で生成&公開するようにしたいと思います。

.NET を対象としているので、まずは Windows もしくは Mono が動く CI サービスを使います。
ここでは好きな Docker イメージが使える CircleCI を使うことにしました。
生成されたドキュメントのホストには Netlify を使用します。

.circleci/config.yml はこのように記述します。

.circleci/config.yml

version: 2
jobs:
  build:
    docker:
      # specify the version you desire here
      - image: mono:latest
 
      # Specify service dependencies here if necessary
      # CircleCI maintains a library of pre-built images
      # documented at https://circleci.com/docs/2.0/circleci-images/
      # - image: circleci/mongo:3.4.4
 
    working_directory: ~/repo
 
    steps:
      - checkout
 
      - run:
          name: Install dependencies
          command: |
            apt update
            apt install -yq unzip wget > /dev/null 2>&1
      - run:
          name: Install docfx
          command: |
            wget -q 'https://github.com/dotnet/docfx/releases/download/v2.39.1/docfx.zip' -O docfx.zip
            unzip -q docfx.zip -d docfx/
      - run:
          name: Generate documents by docfx
          command: |
            mono ./docfx/docfx.exe ./Source/Sagitta.Docs/docfx.json
      - run:
          name: Install netlifyctl
          command: |
            wget -qO- 'https://cli.netlify.com/download/latest/linux' | tar xz
      - deploy:
          name: Deployment task
          command: |
            if [ "${CIRCLE_BRANCH}" == "master" ]; then
              ./netlifyctl deploy --publish-directory "./docs" --access-token $NETLIFY_ACCESS_TOKEN --site-id $NETLIFY_SITE_ID
            fi

XML ドキュメントコメントからのドキュメント生成には DocFX を使います。
そのため、まずは DocFX を GitHub から DL し、展開しておきます。

次に、 Mono 経由で DoxFX を起動し、対象のプロジェクトを設定しておきます。
詳しくは DoxFX のドキュメントを参照してください。

最後に、 Netlify の CLI ツールをインストールし、
master ブランチの場合のみ deploy コマンドを叩きます。

NETLIFY_ACCESS_TOKEN は Netlify のアクセストークンを、
NETLIFY_SITE_ID は Netlify で設定したサイト固有の API ID を環境変数に設定しておきます。

--publish-directory には、 DoxFX で生成したドキュメントへのパスを指定します。
今回、 docfx.json で docs に出力するように設定しているので、 docs を指定しています。

{
  "build": {
    "dest": "../../docs",
    "template": ["default"]
  }
}

少しでも楽がしたいのでこういう構成が生まれました。
どうやら .NET Core で DocFX を動かせるようにする計画があるらしいので、
半年後くらいには CircleCI 経由せず、 Netlify だけで生成、公開できるようになるかも。

では(๑╹﹃╹)