ライブラリなどを公開する場合、ソースコード内に記述したコメントなどを元に、
自動でドキュメントを生成し、公開してくれていると非常に助かったりします。
例えば、 .NET の場合は XML ドキュメントコメントを書いてくれれば、非常に助かります。
今回は、それを master ブランチに push した際、自動で生成&公開するようにしたいと思います。
.NET を対象としているので、まずは Windows もしくは Mono が動く CI サービスを使います。
ここでは好きな Docker イメージが使える CircleCI を使うことにしました。
生成されたドキュメントのホストには Netlify を使用します。
.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 だけで生成、公開できるようになるかも。
では(๑╹﹃╹)