From f917040e9ad28bbc69c208f83643fc378cbe3799 Mon Sep 17 00:00:00 2001 From: ssdfasd <2156608475@qq.com> Date: Fri, 10 Apr 2026 17:12:55 +0800 Subject: [PATCH] docs(api): add gaussian splat pages and fix doc generators --- .../Resources/GaussianSplat/GaussianSplat.md | 25 +++-- .../GaussianSplat/GaussianSplat.md | 58 +++++----- .../GaussianSplatArtifactIO.md | 43 +++---- .../GaussianSplatLoader.md | 13 +-- docs/api/_meta/rebuild-status.md | 6 +- ...generate_core_resources_canonical_pages.py | 61 +++++++++- docs/api/_tools/scaffold_parallel_layout.py | 106 +++++++++++++----- ...结构阶段进度_XCEditor与Model收口_2026-04-10.md | 38 +++++++ 8 files changed, 246 insertions(+), 104 deletions(-) create mode 100644 docs/plan/API文档目录结构阶段进度_XCEditor与Model收口_2026-04-10.md diff --git a/docs/api/XCEngine/Resources/GaussianSplat/GaussianSplat.md b/docs/api/XCEngine/Resources/GaussianSplat/GaussianSplat.md index 4ffa594c..092807ad 100644 --- a/docs/api/XCEngine/Resources/GaussianSplat/GaussianSplat.md +++ b/docs/api/XCEngine/Resources/GaussianSplat/GaussianSplat.md @@ -4,20 +4,20 @@ **类型**: `submodule` -**描述**: Gaussian Splat 资源子模块，覆盖运行时 splat payload、artifact I/O 与对应 loader。 +**描述**: 3DGS 资源子模块，覆盖 `GaussianSplat` 运行时资源、`.xcgsplat` artifact 协议与标准 loader。 -## 概述 +## 概览 -`Resources::GaussianSplat` 当前负责把压缩后的 splat payload 以资源形式接入引擎。按当前实现，这条链路分成三层： +`Resources/GaussianSplat` 当前把 3DGS 资源链拆成三层： -1. `GaussianSplat` - - 保存 metadata、section table 与原始 payload -2. `GaussianSplatArtifactIO` - - 读写 `.xcgsplat` artifact，并在加载时构造 `GaussianSplat` -3. `GaussianSplatLoader` - - 作为 `IResourceLoader` 接入 `ResourceManager` +- [GaussianSplat](GaussianSplat/GaussianSplat.md) + 运行时资源对象，保存 section 元数据与 payload。 +- [GaussianSplatArtifactIO](GaussianSplatArtifactIO/GaussianSplatArtifactIO.md) + `.xcgsplat` 的写入与回读协议。 +- [GaussianSplatLoader](GaussianSplatLoader/GaussianSplatLoader.md) + 只面向 `.xcgsplat` artifact 的标准资源加载器。 -和 [Model](../Model/Model.md) / [Mesh](../Mesh/Mesh.md) 这类图结构资源不同，`GaussianSplat` 更像“多 section 二进制块 + metadata”的只读 payload 资源。 +这条链路当前只负责资源层与 artifact 层，不在这里直接创建 GPU residency，也不在这里承担最终渲染 pass。 ## 头文件 @@ -28,5 +28,6 @@ ## 相关文档 - [Resources](../Resources.md) -- [Core / Asset](../../Core/Asset/Asset.md) -- [Model](../Model/Model.md) +- [Volume](../Volume/Volume.md) +- [Rendering](../../Rendering/Rendering.md) +- [API 总索引](../../../main.md) diff --git a/docs/api/XCEngine/Resources/GaussianSplat/GaussianSplat/GaussianSplat.md b/docs/api/XCEngine/Resources/GaussianSplat/GaussianSplat/GaussianSplat.md index d05dcdad..791a7717 100644 --- a/docs/api/XCEngine/Resources/GaussianSplat/GaussianSplat/GaussianSplat.md +++ b/docs/api/XCEngine/Resources/GaussianSplat/GaussianSplat/GaussianSplat.md @@ -8,54 +8,62 @@ **源文件**: `engine/src/Resources/GaussianSplat/GaussianSplat.cpp` -**描述**: Gaussian Splat 运行时资源对象，保存 metadata、section table 与原始 payload。 +**描述**: 3DGS 运行时资源对象，保存 splat metadata、section table 和 artifact payload 字节数据。 -## 概述 +## 概览 -`GaussianSplat` 当前把 splat 数据拆成三层状态： +`GaussianSplat` 是当前 3DGS 资源在运行时的最小封装。它并不直接创建 GPU buffer 或 texture，而是把 `.xcgsplat` loader 读出的内容保存在 CPU 侧，供后续： -- `GaussianSplatMetadata` - - 内容版本、splat/chunk/camera 数量、bounds 与 section format -- `GaussianSplatSection` - - 每个 section 的类型、格式、payload 偏移、大小和元素布局 -- `payload` - - 实际的二进制块数据 +- 资源系统缓存 +- artifact round-trip +- 渲染缓存层上传 GPU 资源 -这让资源对象可以在不理解每种 section 语义的前提下，统一保存和查询 payload。 +使用。 + +## 声明概览 + +| 声明 | 类型 | 说明 | +|------|------|------| +| `GaussianSplatSectionType` | `enum class` | section 语义类型，区分 `Positions`、`Color`、`SH`、`Chunks` 等 payload 分区。 | +| `GaussianSplatSectionFormat` | `enum class` | section 数据布局格式，描述 float/packed/color/sh/chunk 等编码方式。 | +| `GaussianSplatSection` | `struct` | 单个 section 的偏移、大小、元素数和 stride 描述。 | +| `GaussianSplatMetadata` | `struct` | 资源级 metadata，记录 splat 数量、bounds 与各 section 的格式。 | ## 当前状态模型 | 字段 | 说明 | |------|------| -| `m_metadata` | 版本、bounds、计数和 section format | -| `m_sections` | section 描述表 | -| `m_payload` | 原始二进制 payload | +| `m_metadata` | 当前资源的 splat 数量、bounds、chunk/camera 计数与 section format | +| `m_sections` | section table，描述每个 payload 分段的偏移和布局 | +| `m_payload` | artifact 读回的原始 payload 字节数组 | ## 当前实现行为 - `CreateOwned(...)` - - 先验证 section table，再接管 metadata / sections / payload -- `FindSection(...)` - - 按 `GaussianSplatSectionType` 查找 section 记录 -- `GetSectionData(...)` - - 根据 section 的 `dataOffset` 返回 payload 里的起始地址 + - 先校验 section 类型唯一且范围不越界 + - 成功时接管 section 与 payload 所有权，并把资源标记为 valid - `Clear()` - - 清空 metadata、section table 和 payload，并把资源标记为 invalid + - 清空 metadata、section table 和 payload，并重置 valid 状态 +- `FindSection(...)` + - 按 section type 线性查找当前资源里的分段定义 +- `GetSectionData(...)` + - 若目标 section 不存在或 `dataSize == 0`，返回 `nullptr` + - 否则返回 payload 中对应偏移的只读指针 - `Release()` - 当前直接执行 `delete this` ## 测试与调用链 -- `tests/Resources/GaussianSplat/test_gaussian_splat.cpp` - - 覆盖 `CreateOwned(...)` 的 metadata / payload 保存与非法 section layout 拒绝 - `engine/src/Resources/GaussianSplat/GaussianSplatArtifactIO.cpp` - - 当前把 artifact 读回结果装配成 `GaussianSplat` + - 当前通过 `CreateOwned(...)` 构造 loader 读回的运行时资源 +- `GaussianSplatLoader` + - 负责把 `.xcgsplat` artifact 交给资源系统并恢复成 `GaussianSplat` ## 当前实现边界 -- 当前对象只提供按 section 粗粒度查询，不做更高层语义解码。 -- `ValidateSections(...)` 会拒绝 `Unknown` section、越界 payload 区间和重复 section type。 -- payload 生命周期完全由资源对象拥有，不借用外部内存。 +- 当前资源只保存 CPU 侧 metadata 和 payload，不直接持有 GPU 资源。 +- section 校验当前只保证类型唯一和边界合法，不做更高层的 3DGS 语义验证。 +- 后续 GPU residency cache 需要自行决定哪些 section 被上传成 buffer、哪些被上传成 texture。 ## 相关文档 diff --git a/docs/api/XCEngine/Resources/GaussianSplat/GaussianSplatArtifactIO/GaussianSplatArtifactIO.md b/docs/api/XCEngine/Resources/GaussianSplat/GaussianSplatArtifactIO/GaussianSplatArtifactIO.md index 48debef9..e325c85e 100644 --- a/docs/api/XCEngine/Resources/GaussianSplat/GaussianSplatArtifactIO/GaussianSplatArtifactIO.md +++ b/docs/api/XCEngine/Resources/GaussianSplat/GaussianSplatArtifactIO/GaussianSplatArtifactIO.md @@ -8,48 +8,41 @@ **源文件**: `engine/src/Resources/GaussianSplat/GaussianSplatArtifactIO.cpp` -**描述**: `.xcgsplat` artifact 的读写入口，负责把 Gaussian Splat payload 序列化到磁盘并恢复成运行时资源。 +**描述**: `.xcgsplat` artifact 的读写入口，负责把 `GaussianSplat` 资源写成磁盘协议并恢复为运行时对象。 -## 概述 +## 概览 `GaussianSplatArtifactIO` 当前公开两个函数： - `WriteGaussianSplatArtifactFile(...)` - - 把 `GaussianSplat` 的 metadata、section table 和 payload 写成 `.xcgsplat` + - 把 `GaussianSplat` 写成 `.xcgsplat` - `LoadGaussianSplatArtifact(...)` - - 读取 `.xcgsplat` 并恢复成 `GaussianSplat` + - 读取 `.xcgsplat` 并恢复 `GaussianSplat` + +这两个函数共同构成当前 3DGS 资源的 artifact 协议边界。 ## 当前实现行为 ### 写入路径 -- 会先解析 artifact 路径并在需要时创建父目录。 -- 文件头 magic 当前校验为 `XCGSP01` 协议。 -- 写入顺序是： - - `GaussianSplatArtifactFileHeader` - - `GaussianSplatArtifactHeader` - - section table - - payload 字节块 +- 会先解析 artifact 路径，必要时创建父目录。 +- 文件头当前写入 `GaussianSplatArtifactFileHeader`，magic 固定校验为 `XCGSP01`。 +- metadata 会序列化 splat 数量、chunk/camera 计数、bounds 和各 section format。 +- section table 会顺序写入 section type、format、offset、size、elementCount 与 stride。 +- 若 payload 非空，最后会把整段 payload 原样写入文件尾。 ### 读取路径 -- 会解析真实路径，必要时回退到 `ResourceManager::Get().GetResourceRoot()`。 -- header 校验失败会直接返回错误的 `LoadResult`。 -- 读取 section table 后会还原成 `GaussianSplatSection` 数组，再读 payload。 -- 成功时通过内部 `CreateOwnedGaussianSplatResource(...)` 构造资源对象。 - -## 测试与调用链 - -- `tests/Resources/GaussianSplat/test_gaussian_splat_loader.cpp` - - 覆盖写 artifact、再由 loader 读回的往返路径 -- `engine/src/Resources/GaussianSplat/GaussianSplatLoader.cpp` - - 当前把实际 `.xcgsplat` 读取委托给 `LoadGaussianSplatArtifact(...)` +- 会先解析真实路径，必要时回退到 `ResourceManager::Get().GetResourceRoot()`。 +- 会校验 file header 和 `kGaussianSplatArtifactSchemaVersion`。 +- 读取 section table 后恢复 `GaussianSplatSection` 数组。 +- payload 读回后会通过内部 `CreateOwnedGaussianSplatResource(...)` 构造运行时资源。 ## 当前实现边界 -- 当前只处理 `.xcgsplat` artifact，不直接解析外部原始 Gaussian Splat 源格式。 -- artifact 的 section 语义依赖 header 里的 metadata/format，不在这里做高层解释。 -- 读取失败时直接返回错误，不做容错修复。 +- 当前只处理 `.xcgsplat` artifact，不直接解析 `.ply` 等 source asset。 +- schema version 不匹配时直接失败，不做向后兼容恢复。 +- artifact 协议当前只保证 section 化 payload 的稳定保存，不承担 GPU 资源预热。 ## 相关文档 diff --git a/docs/api/XCEngine/Resources/GaussianSplat/GaussianSplatLoader/GaussianSplatLoader.md b/docs/api/XCEngine/Resources/GaussianSplat/GaussianSplatLoader/GaussianSplatLoader.md index 043ff3fe..eaecae0b 100644 --- a/docs/api/XCEngine/Resources/GaussianSplat/GaussianSplatLoader/GaussianSplatLoader.md +++ b/docs/api/XCEngine/Resources/GaussianSplat/GaussianSplatLoader/GaussianSplatLoader.md @@ -10,9 +10,9 @@ **描述**: `GaussianSplat` 资源的标准 loader，负责识别 `.xcgsplat` artifact 并通过 `GaussianSplatArtifactIO` 读入运行时资源。 -## 概述 +## 概览 -`GaussianSplatLoader` 继承自 `IResourceLoader`，是 `ResourceManager` 当前注册的 Gaussian Splat 资源入口。实现策略和 `ModelLoader` 类似： +`GaussianSplatLoader` 继承自 `IResourceLoader`，是当前 3DGS 资源进入 `ResourceManager` 的正式入口。它的实现刻意保持很窄： - 只接受 `.xcgsplat` - 实际反序列化委托给 `LoadGaussianSplatArtifact(...)` @@ -38,12 +38,11 @@ - `GetDefaultSettings()` 当前返回 `nullptr` - 文件末尾通过 `REGISTER_RESOURCE_LOADER(GaussianSplatLoader)` 注册到资源系统 -## 测试与调用链 +## 当前实现边界 -- `tests/Resources/GaussianSplat/test_gaussian_splat_loader.cpp` - - 覆盖扩展名判断、非法路径、artifact 往返加载与 `ResourceManager` 注册 -- `engine/src/Core/Asset/ResourceManager.cpp` - - 当前持有全局 `GaussianSplatLoader` 并注册到资源系统 +- 当前只面向 `.xcgsplat` artifact，不承担 `.ply` source import。 +- loader 只构造 CPU 侧运行时资源，不直接创建设备侧 GPU 资源。 +- 更底层的 schema 校验与 payload 反序列化继续留在 [GaussianSplatArtifactIO](../GaussianSplatArtifactIO/GaussianSplatArtifactIO.md)。 ## 相关文档 diff --git a/docs/api/_meta/rebuild-status.md b/docs/api/_meta/rebuild-status.md index 2fc2f956..6c23d1dc 100644 --- a/docs/api/_meta/rebuild-status.md +++ b/docs/api/_meta/rebuild-status.md @@ -1,13 +1,13 @@ # API 文档重构状态 -**生成时间**: `2026-04-10 17:07:09` +**生成时间**: `2026-04-10 17:09:30` **来源**: `docs/api/_tools/audit_api_docs.py` ## 摘要 -- Markdown 页面数（全部）: `3934` -- Markdown 页面数（canonical）: `3906` +- Markdown 页面数（全部）: `3969` +- Markdown 页面数（canonical）: `3941` - Public headers 数: `384` - `XCEditor` public headers 数: `64`（canonical 已覆盖 `64`） - `XCEngine` public headers 数: `320`（canonical 已覆盖 `320`） diff --git a/docs/api/_tools/generate_core_resources_canonical_pages.py b/docs/api/_tools/generate_core_resources_canonical_pages.py index bb8aed32..809e0b40 100644 --- a/docs/api/_tools/generate_core_resources_canonical_pages.py +++ b/docs/api/_tools/generate_core_resources_canonical_pages.py @@ -1,6 +1,7 @@ #!/usr/bin/env python3 from __future__ import annotations +import argparse import os import re from dataclasses import dataclass @@ -10,7 +11,11 @@ from pathlib import Path SCRIPT_DIR = Path(__file__).resolve().parent DOC_ROOT = SCRIPT_DIR.parent if SCRIPT_DIR.name == "_tools" else SCRIPT_DIR REPO_ROOT = DOC_ROOT.parents[1] -INCLUDE_ROOT = REPO_ROOT / "engine" / "include" / "XCEngine" +DEFAULT_ROOT_NAME = "XCEngine" +DEFAULT_INCLUDE_ROOT = REPO_ROOT / "engine" / "include" / DEFAULT_ROOT_NAME +INCLUDE_ROOT = DEFAULT_INCLUDE_ROOT +CANONICAL_ROOT_NAME = DEFAULT_ROOT_NAME +CANONICAL_DOC_ROOT = DOC_ROOT / CANONICAL_ROOT_NAME MAIN_INDEX = DOC_ROOT / "main.md" @@ -21,7 +26,7 @@ def dir_index_name(doc_dir: Path) -> str: def dir_index_path(doc_dir: Path) -> Path: return doc_dir / dir_index_name(doc_dir) -MODULES = ( +DEFAULT_MODULES = ( "Audio", "Components", "Core", @@ -34,6 +39,7 @@ MODULES = ( "Scene", "Threading", ) +MODULES = DEFAULT_MODULES TYPE_START_RE = re.compile( r"^(class|struct|enum class|enum)\s+([A-Za-z_]\w*)(?:\s*:\s*public\s+([^{;]+))?" ) @@ -626,7 +632,7 @@ def infer_page_type(stem: str, primary: Declaration | None) -> str: def scope_label(relative_parts: tuple[str, ...]) -> str: if not relative_parts: return "当前模块" - return "`XCEngine/" + "/".join(relative_parts) + "` 子目录" + return f"`{CANONICAL_ROOT_NAME}/" + "/".join(relative_parts) + "` 子目录" def infer_description(stem: str, relative_parts: tuple[str, ...]) -> str: @@ -637,11 +643,20 @@ def relative_link(from_path: Path, to_path: Path) -> str: return os.path.relpath(to_path, from_path.parent).replace("\\", "/") +def canonical_header_reference(header_path: Path) -> str: + parts = list(header_path.parts) + if "include" in parts: + include_index = parts.index("include") + if include_index + 1 < len(parts): + return Path(*parts[include_index + 1 :]).as_posix() + return header_path.relative_to(INCLUDE_ROOT.parent).as_posix() + + def build_page(header_path: Path) -> tuple[str, dict[str, str]]: - relative_header = header_path.relative_to(INCLUDE_ROOT.parent).as_posix() + relative_header = canonical_header_reference(header_path) relative_doc_dir = header_path.parent.relative_to(INCLUDE_ROOT) stem = header_path.stem - doc_path = DOC_ROOT / "XCEngine" / relative_doc_dir / stem / f"{stem}.md" + doc_path = CANONICAL_DOC_ROOT / relative_doc_dir / stem / f"{stem}.md" lines = header_path.read_text(encoding="utf-8", errors="ignore").splitlines() namespace_map = build_namespace_map(lines) @@ -792,11 +807,45 @@ def refresh_dir_index(include_dir: Path, doc_dir: Path) -> None: def main() -> int: + parser = argparse.ArgumentParser(description="Generate canonical API pages from public headers.") + 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.", + ) + parser.add_argument( + "--modules", + nargs="*", + default=None, + help="Optional explicit top-level module list. Defaults to legacy XCEngine modules or auto-detected directories for other roots.", + ) + args = parser.parse_args() + + global INCLUDE_ROOT, CANONICAL_ROOT_NAME, CANONICAL_DOC_ROOT, MODULES + INCLUDE_ROOT = Path(args.include_root).resolve() + CANONICAL_ROOT_NAME = args.root_name + CANONICAL_DOC_ROOT = DOC_ROOT / CANONICAL_ROOT_NAME + if args.modules: + MODULES = tuple(args.modules) + elif INCLUDE_ROOT == DEFAULT_INCLUDE_ROOT and CANONICAL_ROOT_NAME == DEFAULT_ROOT_NAME: + MODULES = DEFAULT_MODULES + else: + MODULES = tuple( + path.name + for path in sorted(INCLUDE_ROOT.iterdir()) + if path.is_dir() + ) + generated = 0 method_generated = 0 for module in MODULES: include_module_dir = INCLUDE_ROOT / module - doc_module_dir = DOC_ROOT / "XCEngine" / module + doc_module_dir = CANONICAL_DOC_ROOT / module headers = sorted(include_module_dir.rglob("*.h")) for header in headers: stem = header.stem diff --git a/docs/api/_tools/scaffold_parallel_layout.py b/docs/api/_tools/scaffold_parallel_layout.py index bb79523e..e48b5dff 100644 --- a/docs/api/_tools/scaffold_parallel_layout.py +++ b/docs/api/_tools/scaffold_parallel_layout.py @@ -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 diff --git a/docs/plan/API文档目录结构阶段进度_XCEditor与Model收口_2026-04-10.md b/docs/plan/API文档目录结构阶段进度_XCEditor与Model收口_2026-04-10.md new file mode 100644 index 00000000..bdac4974 --- /dev/null +++ b/docs/plan/API文档目录结构阶段进度_XCEditor与Model收口_2026-04-10.md @@ -0,0 +1,38 @@ +# API 文档目录结构阶段进度：XCEditor 与 Model 收口 + +## 本阶段范围 + +- 新建 `docs/api/XCEditor/**` canonical 目录树，并生成 `new_editor/include/XCEditor/**` 对应的 header 总览页与方法页。 +- 新建 `docs/api/XCEngine/Resources/Model/Model.md` 模块索引，并生成 `Model` / `ModelArtifactIO` / `ModelLoader` / `AssimpModelImporter` 对应页面。 +- 处理并发新增的 `docs/api/XCEngine/Resources/GaussianSplat/**`，补齐模块索引与 `GaussianSplat` / `GaussianSplatArtifactIO` / `GaussianSplatLoader` 页面。 +- 修正目录脚手架与 canonical 生成器的两个问题： + - 根索引页错误把 `XCEditor` 当成普通子目录，生成了失效的 `../api.md` 链接。 + - 窄范围生成 `Resources/Model` 时，头文件引用缺少 `XCEngine/` 前缀。 + +## 当前结果 + +执行时间：`2026-04-10` + +审计命令： + +```powershell +python -B docs/api/_tools/audit_api_docs.py +``` + +审计结果： + +- `Public headers: 381` +- `Valid header refs (canonical): 381` +- `Invalid header refs: 0` +- `Editor source headers: 144` +- `Valid source refs (Editor canonical): 144` +- `Invalid source refs: 0` +- `Broken .md links: 0` +- `Missing directory index pages: 0` + +## 并行协作说明 + +- `docs/api/XCEditor/**` 本轮已经落成，不再作为待认领空树任务。 +- `docs/api/XCEngine/Resources/Model/**` 本轮已经补齐目录索引与 header 页面，不再重复认领。 +- `docs/api/XCEngine/Resources/GaussianSplat/**` 也已补齐，如头文件继续扩展，请直接在现有树上增量同步。 +- 后续如果 `new_editor/include/XCEditor/**` 或 `engine/include/XCEngine/Resources/Model/**` 再发生结构变动，应直接基于当前树增量同步，不要回退到“先补目录骨架”的阶段。