整理: APIドキュメント生成コードの段階化 (VOICEVOX#865)

* Refactor: APIドキュメント生成コードの段階化 * Fix: lint * Refactor: `Path` ベースファイル保存への変更 * Fix: lint
aoirint · Dec 22, 2023 · 3935862 · 3935862
1 parent f251dfe
commit 3935862
Show file tree

Hide file tree

Showing 2 changed files with 35 additions and 15 deletions.
diff --git a/.github/workflows/upload-gh-pages.yml b/.github/workflows/upload-gh-pages.yml
@@ -1,3 +1,5 @@
+# API docs HTML ファイルを生成し、`gh-pages` ブランチへの push によって GitHub Pages 上のドキュメントとして公開
+
 name: upload-docs
 
 on:

diff --git a/build_util/make_docs.py b/build_util/make_docs.py
@@ -1,25 +1,18 @@
 import json
+from pathlib import Path
 
 from voicevox_engine.dev.core import mock as core
 from voicevox_engine.dev.synthesis_engine.mock import MockTTSEngine
 from voicevox_engine.preset import PresetManager
 from voicevox_engine.setting import USER_SETTING_PATH, SettingLoader
 from voicevox_engine.utility import engine_root
 
-if __name__ == "__main__":
-    import run
 
-    app = run.generate_app(
-        synthesis_engines={"mock": MockTTSEngine(speakers=core.metas())},
-        latest_core_version="mock",
-        setting_loader=SettingLoader(USER_SETTING_PATH),
-        preset_manager=PresetManager(  # FIXME: impl MockPresetManager
-            preset_path=engine_root() / "presets.yaml",
-        ),
-    )
-    with open("docs/api/index.html", "w") as f:
-        f.write(
-            """<!DOCTYPE html>
+def generate_api_docs_html(schema: str) -> str:
+    """OpenAPI schema から API ドキュメント HTML を生成する"""
+
+    return (
+        """<!DOCTYPE html>
 <html lang="ja">
 <head>
     <title>voicevox_engine API Document</title>
@@ -34,5 +27,30 @@
     </script>
 </body>
 </html>"""
-            % json.dumps(app.openapi())
-        )
+        % schema
+    )
+
+
+if __name__ == "__main__":
+
+    import run
+
+    # FastAPI の機能を用いて OpenAPI schema を生成する
+    app = run.generate_app(
+        synthesis_engines={"mock": MockTTSEngine(speakers=core.metas())},
+        latest_core_version="mock",
+        setting_loader=SettingLoader(USER_SETTING_PATH),
+        preset_manager=PresetManager(  # FIXME: impl MockPresetManager
+            preset_path=engine_root() / "presets.yaml",
+        ),
+    )
+    api_schema = json.dumps(app.openapi())
+
+    # API ドキュメント HTML を生成する
+    api_docs_html = generate_api_docs_html(api_schema)
+
+    # HTML ファイルとして保存する
+    api_docs_root = Path("docs/api")  # 'upload-docs' workflow の対象
+    output_path = api_docs_root / "index.html"
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(api_docs_html)