更新履歴: Unity プロジェクトの API ドキュメントも生成出来るように修正
docfx
を使うと API リファレンスをイイ感じに作ってくれて GitHub ページでホストされて見られるようになる。ってイメージですが、全然そんなことはないです。何もしないと 404 NOT FOUND
、ファイル名を知らないとアクセスすらできません。
Unity プロジェクトの場合はさらに面倒です。
UNITY_EDITOR
等のプリプロセッサーディレクティブが設定されていない為、エディター拡張やソースジェネレーター的なクラスはドキュメントの生成が行われません。
DefineConstants
が適切に設定された(=Unityが生成した) .csproj
をアップロードする必要があります。#if UNITY_2021_3_OR_NEWER
を加えている場合もドキュメント生成が行われません。
なので、余計な手順なしで一発でページ公開まで実現できる GitHub Actions を作りました。
🚀 こんな時に便利
-
docs/
フォルダーをリポジトリに追加したくない - でも GitHub ページで API リファレンスは見られるようにしたい
- よそ行のしっかりしたものじゃなくて良い
- 移動中とか寝落ち前にチラ見して、ああしようこうしようが出来ればイイ
-
.csproj
無しで.cs
ファイルだけで上手いこと生成して欲しい
加えて、
- ソースコード冒頭のコメントブロックを Markdown ドキュメントとして切り出したい
も出来ます。
HeaderDoc
1 の自動抽出
最近は個別のドキュメントではなく、ソースコード冒頭にコメントとして 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
が対応していないのを示すため
- ※ ロゴがおかしいのは URL 指定に
生成に成功すると、アクションの結果ページに 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 向けライブラリやプロジェクトの場合は記載の方法だと足りない場合があります。
1)設定ファイル・フォルダーの準備
ファイルをいくつか作るだけなので、GitHub にブラウザでアクセスして .
(ドット)を押下、ブラウザ版 VS Code を起動しての作業で十分でしょう。
出力されたHTMLファイルをアップロードしないのであれば、Unity で無意味なファイルが表示されないようにフォルダー名を .docfx
(ドット始まり)にします。
※ 以降はすべて .docfx
フォルダー内で作業します。
docfx-filter.yml
System
UnityEngine
等の基本クラスからの継承メンバーは非表示にするフィルターを設定します。
.yaml
ではなく.yml
です。JSON の拡張子を.jsn
にしてる人なんていないのに YAML ファイルの拡張子としては何故か.yml
が広く使われているようです。謎。
上手いこと設定します。
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/
2)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
以上。
お疲れ様でした。
-
厳密には HeaderDoc ではなくファイル冒頭のコメントブロック(
/*
~*/
)部分。コーディング規約に記載があったりするけど呼び方が無いんですよね。アレ。 ↩