xuanchi/XCEngine
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(api): add gaussian splat pages and fix doc generators

Browse Source
This commit is contained in:
ssdfasd
2026-04-10 17:12:55 +08:00
parent 66ae9ec919
commit f917040e9a
8 changed files with 246 additions and 104 deletions
Download Patch File Download Diff File Expand all files Collapse all files

106
docs/api/_tools/scaffold_parallel_layout.py
View File

@@ -1,6 +1,7 @@
#!/usr/bin/env python3
from __future__ import annotations
import argparse
import os
from dataclasses import dataclass
from pathlib import Path
@@ -9,11 +10,12 @@ from pathlib import Path
SCRIPT_DIR = Path(__file__).resolve().parent
API_ROOT = SCRIPT_DIR.parent if SCRIPT_DIR.name == "_tools" else SCRIPT_DIR
REPO_ROOT = API_ROOT.parents[1]
INCLUDE_ROOT = REPO_ROOT / "engine" / "include" / "XCEngine"
DOC_ROOT = API_ROOT / "XCEngine"
DEFAULT_ROOT_NAME = "XCEngine"
DEFAULT_INCLUDE_ROOT = REPO_ROOT / "engine" / "include" / DEFAULT_ROOT_NAME
DESCRIPTION_MAP = {
DESCRIPTION_MAPS = {
"XCEngine": {
"XCEngine": "与 `engine/include/XCEngine` 平行的 API 文档根目录。",
"XCEngine/Audio": "音频系统、混音器、效果器与后端接口。",
"XCEngine/Components": "组件系统与游戏对象 API。",
@@ -38,6 +40,26 @@ DESCRIPTION_MAP = {
"XCEngine/RHI/OpenGL": "OpenGL 后端 public headers。",
"XCEngine/Scene": "场景与场景管理器 API。",
"XCEngine/Threading": "线程封装、同步原语和任务系统。",
},
"XCEditor": {
"XCEditor": "与 `new_editor/include/XCEditor` 平行的 API 文档根目录。",
"XCEditor/Collections": "Editor 集合视图与滚动/重命名/标签条等组合控件协议。",
"XCEditor/Fields": "Editor inspector 字段控件、交互状态机与 property-grid 协议。",
"XCEditor/Foundation": "Editor 命令、快捷键与主题等基础协作契约。",
"XCEditor/Shell": "Editor 工作区、panel、dock、viewport 与 menu 壳层装配协议。",
"XCEditor/Widgets": "Editor 专用绘制/布局辅助与通用 widget primitive helper。",
},
}
NAMESPACE_MAPS = {
"XCEditor": {
"XCEditor": "XCEngine::UI::Editor",
"XCEditor/Collections": "XCEngine::UI::Editor::Widgets",
"XCEditor/Fields": "XCEngine::UI::Editor::Widgets",
"XCEditor/Foundation": "XCEngine::UI::Editor",
"XCEditor/Shell": "XCEngine::UI::Editor",
"XCEditor/Widgets": "XCEngine::UI::Editor::Widgets",
},
}
@@ -46,48 +68,64 @@ class DirInfo:
include_dir: Path
doc_dir: Path
relative: str
root_name: str
namespace: str
type_label: str
description: str
def to_namespace(relative: str) -> str:
if relative == "XCEngine":
return "XCEngine"
def to_namespace(relative: str, root_name: str) -> str:
mapped = NAMESPACE_MAPS.get(root_name, {}).get(relative)
if mapped:
return mapped
if relative == root_name:
return root_name
return "::".join(relative.split("/"))
def get_type_label(relative: str) -> str:
if relative == "XCEngine":
def get_type_label(relative: str, root_name: str) -> str:
if relative == root_name:
return "module-root"
if relative.count("/") == 1:
return "module"
return "submodule"
def get_description(relative: str) -> str:
return DESCRIPTION_MAP.get(relative, "与当前 public headers 平行的文档目录节点。")
def get_description(relative: str, root_name: str) -> str:
return DESCRIPTION_MAPS.get(root_name, {}).get(
relative,
"与当前 public headers 平行的文档目录节点。",
)
def iter_include_dirs() -> list[DirInfo]:
dirs = [INCLUDE_ROOT]
dirs.extend(path for path in sorted(INCLUDE_ROOT.rglob("*")) if path.is_dir())
def iter_include_dirs(
include_root: Path,
doc_root: Path,
root_name: str,
) -> list[DirInfo]:
dirs = [include_root]
dirs.extend(path for path in sorted(include_root.rglob("*")) if path.is_dir())
items: list[DirInfo] = []
for include_dir in dirs:
relative = "XCEngine"
if include_dir != INCLUDE_ROOT:
relative = "XCEngine/" + include_dir.relative_to(INCLUDE_ROOT).as_posix()
relative = root_name
if include_dir != include_root:
relative = root_name + "/" + include_dir.relative_to(include_root).as_posix()
doc_dir = DOC_ROOT if include_dir == INCLUDE_ROOT else DOC_ROOT / include_dir.relative_to(INCLUDE_ROOT)
doc_dir = (
doc_root
if include_dir == include_root
else doc_root / include_dir.relative_to(include_root)
)
items.append(
DirInfo(
include_dir=include_dir,
doc_dir=doc_dir,
relative=relative,
namespace=to_namespace(relative),
type_label=get_type_label(relative),
description=get_description(relative),
root_name=root_name,
namespace=to_namespace(relative, root_name),
type_label=get_type_label(relative, root_name),
description=get_description(relative, root_name),
)
)
return items
@@ -116,8 +154,8 @@ def build_dir_index(info: DirInfo) -> str:
index_path = dir_index_path(info.doc_dir)
title = info.relative.split("/")[-1]
if info.relative == "XCEngine":
title = "XCEngine API 平行目录"
if info.relative == info.root_name:
title = f"{info.root_name} API 平行目录"
lines: list[str] = []
lines.append(f"# {title}")
@@ -156,7 +194,7 @@ def build_dir_index(info: DirInfo) -> str:
lines.append("## 相关文档")
lines.append("")
if info.relative == "XCEngine":
if info.relative == info.root_name:
lines.append("- [API 总索引](../main.md)")
lines.append("- [API 文档重构状态](../_meta/rebuild-status.md)")
else:
@@ -167,12 +205,28 @@ def build_dir_index(info: DirInfo) -> str:
def main() -> int:
DOC_ROOT.mkdir(parents=True, exist_ok=True)
infos = iter_include_dirs()
parser = argparse.ArgumentParser(description="Scaffold parallel API directory index pages.")
parser.add_argument(
"--root-name",
default=DEFAULT_ROOT_NAME,
help="Canonical doc root name under docs/api, e.g. XCEngine or XCEditor.",
)
parser.add_argument(
"--include-root",
default=str(DEFAULT_INCLUDE_ROOT),
help="Source include root mirrored by the canonical doc tree.",
)
args = parser.parse_args()
include_root = Path(args.include_root).resolve()
doc_root = API_ROOT / args.root_name
doc_root.mkdir(parents=True, exist_ok=True)
infos = iter_include_dirs(include_root, doc_root, args.root_name)
for info in infos:
info.doc_dir.mkdir(parents=True, exist_ok=True)
dir_index_path(info.doc_dir).write_text(build_dir_index(info), encoding="utf-8")
print(f"Generated {len(infos)} directory index files under {DOC_ROOT}")
print(f"Generated {len(infos)} directory index files under {doc_root}")
return 0