docs: mkdocs前処理の自動同期とスクリプト説明を整理

Author: KKT89

README.md

@@ -8,16 +8,12 @@
 
 ```shell
 $ uv sync
-$ uv run python scripts/sync_library_index.py --write
 $ uv run mkdocs serve
 ```
 
-`mkdocs.yml` の `nav` を変更していない場合は、2行目（`sync_library_index.py --write`）は省略可能です。
+### 開発用スクリプト
 
-### ヘッダ結合（1ファイル化）について
-
-- `mkdocs serve/build` の前に `include/**/*.hpp` から `bundled/` を自動生成します（`scripts/mkdocs_hooks.py`）。
-- 各ライブラリページの「Bundled (Copy & Paste)」はこの `bundled/` を参照します。
+スクリプトに関する説明は [`scripts/README.md`](scripts/README.md) に記載しています。
 
 ## ライブラリ使用方法
 

scripts/README.md

@@ -0,0 +1,22 @@
+# scripts/
+
+ドキュメント生成まわりの補助スクリプトです。
+
+## `sync_library_index.py`
+
+- 役割: `mkdocs.yml` の `nav` から `docsrc/library/index.md` を生成・同期します。
+- 通常運用: `mkdocs serve/build` 実行時に `scripts/mkdocs_hooks.py` から自動実行されるため、手動実行は不要です。
+- 手動チェック: `uv run python scripts/sync_library_index.py`
+- 手動更新: `uv run python scripts/sync_library_index.py --write`
+
+## `bundle_header.py`
+
+- 役割: `#include` を展開して、1ファイル化済みヘッダ（`bundled/`）を生成します。
+- 通常運用: `mkdocs serve/build` 実行時に `scripts/mkdocs_hooks.py` から自動実行されます。
+
+## `mkdocs_hooks.py`
+
+- 役割: MkDocs の `on_pre_build` フックで前処理を実行します。
+- 実行内容:
+  - `sync_library_index.py` で `docsrc/library/index.md` を同期
+  - `bundle_header.py` で `bundled/` を生成

scripts/mkdocs_hooks.py

@@ -9,6 +9,7 @@
 BUNDLE_ROOT = ROOT / "bundled"
 VERIFY_ROOT = ROOT / "verify"
 BUNDLE_SCRIPT = ROOT / "scripts" / "bundle_header.py"
+SYNC_SCRIPT = ROOT / "scripts" / "sync_library_index.py"
 
 
 def _load_bundler():
@@ -20,7 +21,19 @@ def _load_bundler():
     return module.bundle_header
 
 
+def _load_library_index_syncer():
+    spec = importlib.util.spec_from_file_location("sync_library_index", SYNC_SCRIPT)
+    if spec is None or spec.loader is None:
+        raise RuntimeError(f"failed to load: {SYNC_SCRIPT}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module.sync_library_index
+
+
 def on_pre_build(config):
+    sync_library_index = _load_library_index_syncer()
+    sync_library_index(write=True)
+
     bundle_header = _load_bundler()
     for path in INCLUDE_ROOT.rglob("*.hpp"):
         rel = path.relative_to(INCLUDE_ROOT)

scripts/sync_library_index.py

@@ -75,21 +75,33 @@ def render_library_index(groups: list[tuple[str, list[tuple[str, str]]]]) -> str
     return "\n".join(lines).rstrip() + "\n"
 
 
+def sync_library_index(*, write: bool) -> tuple[bool, str, str]:
+    expected = render_library_index(load_library_nav_groups())
+    current = LIBRARY_INDEX_MD.read_text(encoding="utf-8") if LIBRARY_INDEX_MD.exists() else ""
+    changed = current != expected
+
+    if write and changed:
+        LIBRARY_INDEX_MD.parent.mkdir(parents=True, exist_ok=True)
+        LIBRARY_INDEX_MD.write_text(expected, encoding="utf-8")
+
+    return changed, current, expected
+
+
 def main() -> int:
     parser = argparse.ArgumentParser()
     parser.add_argument("--write", action="store_true", help="docsrc/library/index.md を更新する")
     args = parser.parse_args()
 
-    expected = render_library_index(load_library_nav_groups())
-    current = LIBRARY_INDEX_MD.read_text(encoding="utf-8") if LIBRARY_INDEX_MD.exists() else ""
+    changed, current, expected = sync_library_index(write=args.write)
 
     if args.write:
-        LIBRARY_INDEX_MD.parent.mkdir(parents=True, exist_ok=True)
-        LIBRARY_INDEX_MD.write_text(expected, encoding="utf-8")
-        print(f"updated: {LIBRARY_INDEX_MD}")
+        if changed:
+            print(f"updated: {LIBRARY_INDEX_MD}")
+        else:
+            print(f"already up-to-date: {LIBRARY_INDEX_MD}")
         return 0
 
-    if current == expected:
+    if not changed:
         print("OK: docsrc/library/index.md is in sync with mkdocs.yml")
         return 0