docs: migrate documentation site to zensical (#41)

* build: migrate documentation site to zensical

* fix: restore default theme and side navigation

* docs: automate API reference generation

Signed-off-by: Illustar0 <me@illustar0.com>

---------

Signed-off-by: Illustar0 <me@illustar0.com>

Author: Illustar0

.github/workflows/build-docs.yaml

@@ -34,7 +34,8 @@ jobs:
         id: build
         run: |
           uv sync --extra docs
-          uv run mkdocs build
+          uv run python scripts/generate_api_reference.py
+          uv run zensical build
 
       - name: Upload static files as artifact
         id: deployment
@@ -51,4 +52,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v5
+        uses: actions/deploy-pages@v5

README.md

@@ -86,13 +86,17 @@ with EPortalClient(portal.portal_server_url, bind_address=portal.user_ip) as cli
 
 - 使用文档：<https://illustar0.github.io/ZZU.Py/>
 - API 参考：<https://illustar0.github.io/ZZU.Py/reference/api/>
+- 文档站点由 `Zensical` 构建
 
 ## 开发
 
 项目使用 `uv` 管理环境和命令。
 
 ```bash
 uv sync --extra develop,docs
+uv run python scripts/generate_api_reference.py
+uv run zensical serve
+uv run zensical build
 ruff format zzupy
 ruff check zzupy
 ty check zzupy

docs/index.md

@@ -79,7 +79,10 @@ with EPortalClient(portal.portal_server_url, bind_address=portal.user_ip) as cli
 项目使用 `uv` 管理环境，常用命令：
 
 ```bash
-uv sync
+uv sync --extra docs
+uv run python scripts/generate_api_reference.py
+uv run zensical serve
+uv run zensical build
 ruff check
 uv build
 ```

docs/note.md

@@ -1,7 +1,3 @@
----
-hide:
-- navigation
----
 # 逆向笔记
 
 一些在实现 `zzupy` 过程中记录下来的上游接口行为。这里只保留对源码实现有直接帮助的信息。

docs/reference/api.md

@@ -1,17 +1,13 @@
 ---
 title: API
-hide:
-- navigation
 ---
 
-此页由 `mkdocstrings` 根据源码自动生成，适合在以下场景使用：
+<!-- 由 scripts/generate_api_reference.py 自动生成，请勿手动维护模块列表。 -->
+
+此页由 `Zensical` 配合 `mkdocstrings` 根据源码自动生成，适合在以下场景使用：
 
 - 查看公开模块和导出符号
 - 确认方法签名、参数名和返回值
 - 查询 Pydantic 模型字段
 
-如果你更关注接入步骤和调用示例，优先阅读 `Usage`。
-
-::: zzupy
-    options:
-        show_submodules: true
+如果你更关注接入步骤和调用示例，优先阅读 `Usage`。

mkdocs.yml

@@ -27,19 +27,8 @@ develop = [
 ]
 
 docs = [
-    "markdown-callouts>=0.4.0",
-    "markdown-exec>=1.11.0",
-    "mkdocs-git-revision-date-localized-plugin>=1.4.7",
-    "mkdocs-llmstxt>=0.3.1",
-    "mkdocs-minify-plugin>=0.8.0",
-    "mkdocs-redirects>=1.2.2",
-    "mkdocs-section-index>=0.3.10",
-    "mkdocs>=1.6.1",
-    "mkdocs-material>=9.6.20",
-    "mkdocstrings>=0.30.0",
     "mkdocstrings[python]>=0.30.0",
-    "jieba>=0.42.1",
-    "mkdocs-include-markdown-plugin>=7.1.7",
+    "zensical>=0.0.11",
 ]
 
 

pyproject.toml

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+PACKAGE_DIR = ROOT / "zzupy"
+OUTPUT = ROOT / "docs" / "reference" / "api.md"
+
+
+def iter_modules() -> list[str]:
+    modules: list[str] = []
+
+    for path in sorted(PACKAGE_DIR.rglob("*.py")):
+        relative = path.relative_to(ROOT).with_suffix("")
+        parts = list(relative.parts)
+
+        if parts[-1] == "__main__":
+            continue
+        if parts[-1] == "__init__":
+            parts = parts[:-1]
+
+        if not parts:
+            continue
+
+        modules.append(".".join(parts))
+
+    return modules
+
+
+def heading_level(module: str) -> str:
+    depth = module.count(".")
+    return "#" * min(depth + 2, 6)
+
+
+def build_content(modules: list[str]) -> str:
+    lines = [
+        "---",
+        "title: API",
+        "---",
+        "",
+        "<!-- 由 scripts/generate_api_reference.py 自动生成，请勿手动维护模块列表。 -->",
+        "",
+        "此页由 `Zensical` 配合 `mkdocstrings` 根据源码自动生成，适合在以下场景使用：",
+        "",
+        "- 查看公开模块和导出符号",
+        "- 确认方法签名、参数名和返回值",
+        "- 查询 Pydantic 模型字段",
+        "",
+        "如果你更关注接入步骤和调用示例，优先阅读 `Usage`。",
+        "",
+    ]
+
+    for module in modules:
+        lines.extend(
+            [
+                f"{heading_level(module)} `{module}`",
+                "",
+                f"::: {module}",
+                "",
+            ]
+        )
+
+    return "\n".join(lines)
+
+
+def main() -> None:
+    modules = iter_modules()
+    OUTPUT.write_text(build_content(modules), encoding="utf-8")
+
+
+if __name__ == "__main__":
+    main()