docfx + GitHub ページの手抜きテンプレート

^{更新履歴： Unity プロジェクトの API ドキュメントも生成出来るように修正}
 

docfx を使うと API リファレンスをイイ感じに作ってくれて GitHub ページでホストされて見られるようになる。ってイメージですが、全然そんなことはないです。何もしないと 404 NOT FOUND、ファイル名を知らないとアクセスすらできません。

Unity プロジェクトの場合はさらに面倒です。

• UNITY_EDITOR 等のプリプロセッサーディレクティブが設定されていない為、エディター拡張やソースジェネレーター的なクラスはドキュメントの生成が行われません。
  • docfx の仕様上 DefineConstants が適切に設定された（=Unityが生成した） .csproj をアップロードする必要があります。
• 最低保証バージョンより古い Unity でのコンパイルを防ぐために #if UNITY_2021_3_OR_NEWER を加えている場合もドキュメント生成が行われません。

なので、余計な手順なしで一発でページ公開まで実現できる GitHub Actions を作りました。

🚀 こんな時に便利

• docs/ フォルダーをリポジトリに追加したくない
• でも GitHub ページで API リファレンスは見られるようにしたい
• よそ行のしっかりしたものじゃなくて良い
• 移動中とか寝落ち前にチラ見して、ああしようこうしようが出来ればイイ
• .csproj 無しで .cs ファイルだけで上手いこと生成して欲しい

加えて、

• ソースコード冒頭のコメントブロックを Markdown ドキュメントとして切り出したい

も出来ます。

HeaderDoc¹ の自動抽出

最近は個別のドキュメントではなく、ソースコード冒頭にコメントとして Markdown を残すケースが増えてきたので（管理が楽）、それらを自動抽出してドキュメント化する機能も付いています。

つかいかた

リポジトリの設定から Pages を選び Source を GitHub Actions に設定して、

# GitHub ページテンプレートの checkout アクションの後に 👇

- uses: sator-imaging/docfx-pages@v1
  id: deployment   # actions の結果ページにURLを表示したい場合は必要
  with:
    # 必須オプション
    app_name:    'Deploy Test'
    site_title:  'Deploy Test using sator-imaging/docfx-pages'
    site_footer: '<em>HTML tags accepted</em>'
    # その他のオプション
    class_members: ...

です。

アクションを使って生成したウェブサイト

• class_members: 'separatePages' の場合 💬
• class_members: 'samePage' の場合 💬
  • ※ ロゴがおかしいのは URL 指定に docfx が対応していないのを示すため

生成に成功すると、アクションの結果ページに Artifacts として成果物全体が保存されます。古いバージョンを参照したい場合はダウンロードしておきます。
https://docs.github.com/ja/actions/using-workflows/storing-workflow-data-as-artifacts#downloading-or-deleting-artifacts

--

余計なファイルを追加しないでも GitHub ページ化してさっと眺められるのが気に入ってます。

設定画面に記載がありますが、プライベートリポジトリの GitHub ページはソースコードとは違って全世界にまるっと公開されます。ご注意ください。

以上です。お疲れ様でした。

おまけ： docfx セットアップ方法

アクションを使わないで GitHub ページをデプロイする手順はコチラ。

• JSON の設定ファイルを手作業で用意してリポジトリに追加
• ヘッダーと目次の YAML ファイルを手作業で用意して追加
• リポジトリの README.md だけだと 404 NOT FOUND だから index.md を用意して追加
  • （ソースが GitHub Actions だと必要？ 昔は要らなかったような？）
• 余計なクラスが表示されないようにフィルターを用意して追加
• などなど…

Unity 向けライブラリやプロジェクトの場合は記載の方法だと足りない場合があります。

１）設定ファイル・フォルダーの準備

ファイルをいくつか作るだけなので、GitHub にブラウザでアクセスして .（ドット）を押下、ブラウザ版 VS Code を起動しての作業で十分でしょう。

出力されたHTMLファイルをアップロードしないのであれば、Unity で無意味なファイルが表示されないようにフォルダー名を .docfx（ドット始まり）にします。

※ 以降はすべて .docfx フォルダー内で作業します。

docfx-filter.yml

System UnityEngine 等の基本クラスからの継承メンバーは非表示にするフィルターを設定します。

.yaml ではなく .yml です。JSON の拡張子を .jsn にしてる人なんていないのに YAML ファイルの拡張子としては何故か .yml が広く使われているようです。謎。

上手いこと設定します。

参考： https://zenn.dev/kumas/articles/df26e7e5921548#%E3%83%95%E3%82%A3%E3%83%AB%E3%82%BF%E3%83%BC%E3%81%AE%E8%A8%AD%E5%AE%9A

docfx.json

引き続き上記のページを参考に上手いこと設定します。結構面倒ですが、頑張ってください。

index.md

ビックリすることに、README.md があっても何もしてくれません。ファイル名のない URL でのアクセスはすべて 404 NOT FOUND です。

docfx.json の内容によっては全文検索用の JSON ファイルが表示されます。

index.md という名前でファイルを作って README の内容をコピーしておけば、ファイル名無しの URL でアクセスしたときに適切に処理されます。

一応 /README.html と URL 末尾に手入力すれば index.md が無くてもアクセスできます。

toc.yml

なんとヘッダーも空っぽです。とりあえず以下の内容で用意すればリンクが表示されます。

- name: API
  href: api/

作らなかった場合はファイル名を知らないと一切アクセスできません。

api/ と手入力しても 404 NOT FOUND です。ファイル名が必要です。

ちなみに toc.yml を作ったとしても、ヘッダーにあるロゴをクリックすると 404 NOT FOUND です。必要に応じて index.md の項を参照して解決します。

template/public フォルダーの main.js main.css

これらのファイルは無くても動きます。適切に設定すればナビゲーションバーの右側にリンクアイコンを表示できたりします。

参考： https://dotnet.github.io/docfx/docs/template.html?tabs=modern#custom-template

アイコン名は Bootstrap から探して設定します。
https://icons.getbootstrap.jp/

２）GitHub アクションの設定

ファイルをプッシュしたらリポジトリの設定から Pages を選び、モードを GitHub Actions に変更します。

アクションのテンプレは docfx のマニュアルからコピーします。

<docfx-project-path> を適切に設定します。

👇 はフォルダーのパスを .docfx に変更したものです。

# Your GitHub workflow file under .github/workflows/
# Trigger the action on push to main
on:
  push:
    branches:
      - main
  pull_request:
    branches: 
      - 'main'

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false
  
jobs:
  publish-docs:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
    - name: Checkout
      uses: actions/checkout@v3
    - name: Dotnet Setup
      uses: actions/setup-dotnet@v3
      with:
        dotnet-version: 8.x

    - run: dotnet tool update -g docfx
    - run: docfx .docfx/docfx.json

    - name: Setup Pages
      uses: actions/configure-pages@v3
    - name: Upload artifact
      uses: actions/upload-pages-artifact@v2
      with:
        # Upload entire repository
        path: '.docfx/_site'
    - name: Deploy to GitHub Pages
      id: deployment
      uses: actions/deploy-pages@v2

以上。

お疲れ様でした。

1. 厳密には HeaderDoc ではなくファイル冒頭のコメントブロック（/* ~ */）部分。コーディング規約に記載があったりするけど呼び方が無いんですよね。アレ。 ↩