ビルド

すべてのビルドは Makefile 経由で実行します。ターゲットは sphinx-docs/ ディレクトリで実行してください。

ビルドコマンド

コマンド	説明
make install	uv sync で Python 依存をインストールします。
make html	英語サイトをビルド → _build/html/。
make build-ja	日本語サイトをビルド（-D language=ja 指定）→ _build/html_ja/。
make build-all	EN + JA をビルドして _build/site/{en,ja}/ に統合し、Pagefind を実行します。
make gettext	翻訳対象文字列を _build/gettext/*.pot に抽出します。
make update-po	gettext を実行した後、sphinx-intl update -p _build/gettext -l ja を実行します。locale/ja/LC_MESSAGES/ 配下の .po ファイルを更新します。
make serve	EN + JA + assemble + Pagefind を実行し、_build/site/ を http://localhost:8000 で配信します。
make liveserve	英語サイトのみで sphinx-autobuild を実行します（保存時に自動リビルド）。
make linkcheck	全リンクを検証 → _build/linkcheck/。
make pagefind	既存の _build/site/ に対し Pagefind 検索インデックスを生成します。
make lint	ruff check と ruff format --check を実行します。
make test	pytest を実行します。
make check	lint + test。
make clean	_build/ を削除します。

出力

パス	内容
_build/html/	英語 HTML（make html のデフォルト出力。Pages デフォルトの /en/ にも使用）。
_build/html_ja/	日本語 HTML。
_build/site/	/en/ / /ja/ / ルート index.html（/en/ にリダイレクト）/ Pagefind インデックスを含む統合済みバイリンガルサイト。
_build/gettext/	make gettext で抽出された .pot ファイル。
_build/linkcheck/	make linkcheck の結果。

i18n ラウンドトリップ

英語 .md ソースが変更されたら、次のラウンドトリップを実行します:

make update-po           # rebuilds .po files from current sources
# Edit msgstr in locale/ja/LC_MESSAGES/<file>.po
make build-ja            # verify Japanese build
make build-all           # final bilingual assembly

.po 内で msgstr が空のエントリは、日本語ビルド時に Sphinx が英語ソース文字列にフォールバックします。一時的な状態としては許容されますが、リリース前には埋めるべきです。

CI パイプライン

アクティブなワークフローは .github/workflows/docs.yml です。sphinx-docs/** 配下の変更に対する push / PR と手動 dispatch で起動します。

ステージ	ツール	目的
インストール	uv sync	Python 依存をインストール
Lint	ruff check、ruff format --check	スタイル
テスト	pytest	sphinx-docs/tests/ 配下のテストスイート
ビルド	make build-all（予定）	EN + JA + Pagefind
デプロイ	GitHub Pages	main ブランチのみ

全ワークフローファイルの状態（active / opt-in template / 初回リリース時に予定）は .github/workflows/README.md に記載されています。

注釈

リポジトリが private のため GitHub Pages デプロイは現在停止中です（README の "Visibility" ブロック参照）。Pages は初回リリース時の visibility 切替と同時に有効化されます。