Zenn
📘

DocFxとGitHub Actionsでドキュメント生成のCIを構成する

2020/12/31に公開
.NET
GitHub
GitHub Actions
docfx
tech

DocFXにより、.NET (C#, VB.NET, F#) のプロジェクトから、静的HTMLによるドキュメントを生成できます。/// <summary>の要領で記述するXMLドキュメントコメントを集めてきてくれます。

本記事では、DocFXによるドキュメント生成と、生成したHTMLをGitHub Pagesで公開するまでをGitHub Actionsで行う手順を示します。つまり、pull requestをマージするだけで勝手にドキュメントも更新されていくようにします。

成果物(例)

環境

  • GitHub Actions (windows-latest)
    • ubuntu-latest でも可
  • 適当な .NET プロジェクト

対象とする .NET ソリューションのディレクトリ構成は以下の通りと仮定します。いくつかのクラスライブラリが src/ の下にあります。

MyDotNetSolution/
　├ docfx/ (この中は本記事で作成)
　│　├ _site/ (HTML出力先)
　│　└ docfx.json (設定ファイル)
　├ src/
　│　├ MyProject01/
　│　│　 ├ MyProject01.csproj
　│　│　 ├ Class01.cs
　│　│ 　└ ...
　│　└ MyProject02/
　│　　　├ MyProject02.csproj
　│　　　├ Class02.cs
　│　　　└ ...
　└ MyDotNetSolution.sln

DocFXの導入と実行

本家の解説の通りで、特につまづく点はありません。本記事ではChocolateyで導入します。

導入

PS> choco install docfx

MyDotNetSolution の中で docfx を実行します。

PS> cd MyDotNetSolution
PS> docfx init -q -o docfx

-q を外すと、各オプションを対話的に設定できます。

ローカルで表示

さっそくHTMLを見てみるには以下を実行し、http://localhost:8080 をブラウザで開きます。

PS> docfx docfx\docfx.json --serve

ここで上のナビゲーションバーから Api Documentationを押すと各クラスの説明が見られるはずなのですが、まだ設定が漏れているので見られません。

Api Documentation を構成

docfx/docfx.json を開きます。上の metadata の設定を修正し、MyDotNetSolution/src/ 以下の各クラスライブラリプロジェクトを見に行くようにします。

{
  "metadata": [
    {
      "src": [
        {
          "files": [
            "**/*.csproj"
          ],
          "src": "../src"
        }
      ],
      ... (以下略)

ビルドだけ実施

--serve を付けないで実行すると、ローカルにサーバを立てずHTMLの出力までを実施します。結果は既定では _site ディレクトリの下に出てきます。

ただし、これで出力された静的HTMLをブラウザで見ると、上のApi Documentation等と書かれたナビゲーションバーが表示されません。

CORSの問題っぽい？ですので、ローカルではおとなしく --serve で確認するのが良いと思います。GitHub Pagesにアップロードすれば問題なく表示されます。

GitHub Pagesにアップロード

ある既存のリポジトリにGitHub Pagesをつくる前提とし、そのリポジトリに gh-pages という空のブランチをつくり、_site の中にある生成したHTMLをcommit・pushします。

PS> git checkout --orphan gh-pages
PS> git reset --hard 
PS> xcopy C:\MyDotNetSolution\dotfx\_site\* .
PS> git commit -m "GitHub Pages initial commit"
PS> git push origin gh-pages

リポジトリの設定を確認し、以下のような表示になっていればGitHub Pagesの構築に成功しているはずです。

GitHub Actionsの構築

ここまでの手順を自動化しましょう。GitHub Actionsが発動するタイミングは、main (古いリポジトリならmaster) ブランチにマージされるタイミングとします。

.github/workflows/docfx.yml というファイルを新規作成して、以下のように書きます。

name: DocFX

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: windows-2019
    
    steps:
      - name: Checkout
        uses: actions/checkout@v2
        with:
          fetch-depth: 1

      - name: DocFX
        shell: cmd
        run: |
          choco install docfx -y
          docfx docfx\docfx.json

      - name: Upload DocFX packages
        uses: actions/upload-artifact@v2
        with:
          name: docfx_site
          path: ${{ github.workspace }}\docfx\_site

      - name: Publish Documentation on GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: docfx/_site

Upload DocFX packages のところは無くても構いません。GitHub Actionsのアーティファクトとしても残すようにしている処理です。

最後のGitHub Pagesの公開 (gh-pagesブランチへのpush) のステップにはGitHubのトークンが必要です。secrets.GITHUB_TOKEN は事前設定無しに使える値で、このリポジトリのGitHubトークンが入っています。

これで今後、何か実装を変更するpull requestをマージするたびにGitHub Actionsのワークフローが発動します。マージした後に Actions のナビゲーションから様子を見に行きましょう。

まとめ

  • 少ない手順で、.NETプロジェクトに対するドキュメント生成やGitHub ActionsによるCI構築までを実現できました。
  • 老舗のSandcastle Help File Builderに比べ、HTML出力までが軽量でかつ圧倒的に高速です。出力のファイル一式のサイズも小さめです。
  • GitHub Pagesへのpushについては既製品があり、トークンの用意だけで終わります。
  • 少し凝ってみようとすると手掛かりが少なく、途方に暮れている状態です。しかしぶっちゃけ、C#はIntellisenseなどVisualStudioの機能に全力で頼ればいいので、あまりAPIドキュメントに凝らなくていいよな...というのが正直なところで、私の感覚ではこれ以上がんばる気が起きません。
    • issueには「ドキュメント欲しい」「ドキュメント古い」といったのがよく来るので、世間には必要とする人も多いようです。

参考文献

記事

GitHub Actions Marketplace

全環境対応

Ubuntu向け

今回はwindows-latestのGitHub Actionsで構築しましたが、ubuntu-* でも実現可能です。以下の2つはUbuntuのみの対応なので注意しましょう。

Discussion