ドキュメントビルドと公開手順¶

依存関係の準備¶

ドキュメント関連の依存を docs グループで管理しています。初回は次を実行してインストールしてください。

uv sync --group docs

ローカルビルド¶

HTML を生成するにはプロジェクトルートで以下を実行します。

uv run sphinx-build -b html docs docs/_build/html

Makefile のショートカットも利用できます。

cd docs
make html

ビルド結果は docs/_build/html に出力されるため、ブラウザで index.html を開いて確認できます。

リンク検証¶

外部リンクを検証するには linkcheck ビルダーを利用します。

cd docs
make linkcheck

GitHub Pages へのデプロイ¶

リポジトリには Publish Docs ワークフロー（.github/workflows/docs-pages.yml）を追加しています。main ブランチへの push ごとに Sphinx をビルドし、生成物を GitHub Pages（gh-pages ブランチ）へ反映します。

初回のみ GitHub の Settings → Pages でソースを「GitHub Actions」に変更してください。
ワークフローでは uv sync --group docs → uv run sphinx-apidoc → uv run sphinx-build -b html を順に実行し、docs/_build/html をアーティファクト化して Pages にデプロイします。
Pages には .nojekyll を自動生成してアップロードするため、静的アセット（_static など）も確実に配信されます。追加設定は不要です。

手動で公開フローを検証したい場合は、同じコマンド列をローカルで実行し、docs/_build/html の内容をそのまま配信対象にすれば GitHub Pages と一致します。

API リファレンスを更新する際のヒント¶

sphinx-apidoc -o docs/api src/gunn を利用すると自動でスタブを生成できます。
生成済みファイルは必要に応じて MyST Markdown に書き換え、api/index.md の toctree に追加してください。
新しいモジュールを公開する場合は docstring とタイプヒントを整備するとドキュメントが読みやすくなります。