XCEngine/docs/api/_tools/scaffold_parallel_layout.py

#!/usr/bin/env python3
from __future__ import annotations

import os
from dataclasses import dataclass
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"


DESCRIPTION_MAP = {
    "XCEngine": "与 `engine/include/XCEngine` 平行的 API 文档根目录。",
    "XCEngine/Audio": "音频系统、混音器、效果器与后端接口。",
    "XCEngine/Components": "组件系统与游戏对象 API。",
    "XCEngine/Core": "基础类型、事件、IO、容器与数学基础设施。",
    "XCEngine/Core/Asset": "资源句柄、资源管理器、异步加载与依赖图。",
    "XCEngine/Core/Containers": "字符串、数组和哈希表等核心容器。",
    "XCEngine/Core/IO": "资源路径、归档与虚拟文件系统。",
    "XCEngine/Core/Math": "向量、矩阵、几何体与变换数学类型。",
    "XCEngine/Debug": "日志、Profiler 与调试集成接口。",
    "XCEngine/Input": "输入状态查询、输入事件与平台接入接口。",
    "XCEngine/Memory": "分配器与内存管理。",
    "XCEngine/Platform": "窗口、时钟、文件系统和平台抽象。",
    "XCEngine/Platform/Windows": "Windows 平台窗口与输入接入实现。",
    "XCEngine/Resources": "具体资源类型及其加载器。",
    "XCEngine/Resources/AudioClip": "音频资源与音频加载器。",
    "XCEngine/Resources/Material": "材质资源与材质加载器。",
    "XCEngine/Resources/Mesh": "网格资源、导入设置与网格加载器。",
    "XCEngine/Resources/Shader": "着色器资源与着色器加载器。",
    "XCEngine/Resources/Texture": "纹理资源、导入设置与纹理加载器。",
    "XCEngine/RHI": "渲染硬件抽象层及其后端。",
    "XCEngine/RHI/D3D12": "DirectX 12 后端 public headers。",
    "XCEngine/RHI/OpenGL": "OpenGL 后端 public headers。",
    "XCEngine/Scene": "场景与场景管理器 API。",
    "XCEngine/Threading": "线程封装、同步原语和任务系统。",
}


@dataclass
class DirInfo:
    include_dir: Path
    doc_dir: Path
    relative: str
    namespace: str
    type_label: str
    description: str


def to_namespace(relative: str) -> str:
    if relative == "XCEngine":
        return "XCEngine"
    return "::".join(relative.split("/"))


def get_type_label(relative: str) -> str:
    if relative == "XCEngine":
        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 iter_include_dirs() -> 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()

        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),
            )
        )
    return items


def relative_link(source: Path, target: Path) -> str:
    return os.path.relpath(target, source.parent).replace("\\", "/")


def dir_index_name(doc_dir: Path) -> str:
    return f"{doc_dir.name}.md"


def dir_index_path(doc_dir: Path) -> Path:
    return doc_dir / dir_index_name(doc_dir)


def header_doc_page_name(header_name: str) -> str:
    stem = Path(header_name).stem
    return f"{stem}/{stem}.md"


def build_dir_index(info: DirInfo) -> str:
    include_headers = sorted(path.name for path in info.include_dir.glob("*.h"))
    child_dirs = sorted(path.name for path in info.include_dir.iterdir() if path.is_dir())
    index_path = dir_index_path(info.doc_dir)

    title = info.relative.split("/")[-1]
    if info.relative == "XCEngine":
        title = "XCEngine API 平行目录"

    lines: list[str] = []
    lines.append(f"# {title}")
    lines.append("")
    lines.append(f"**命名空间**: `{info.namespace}`")
    lines.append("")
    lines.append(f"**类型**: `{info.type_label}`")
    lines.append("")
    lines.append(f"**描述**: {info.description}")
    lines.append("")
    lines.append("## 概览")
    lines.append("")
    lines.append(
        f"该目录与 `{info.relative}` 对应的 public headers 保持平行，用于承载唯一的 canonical API 文档入口。"
    )
    lines.append("")

    if child_dirs:
        lines.append("## 子目录")
        lines.append("")
        for child in child_dirs:
            lines.append(f"- [{child}]({child}/{child}.md)")
        lines.append("")

    if include_headers:
        lines.append("## 头文件")
        lines.append("")
        for header in include_headers:
            page_name = header_doc_page_name(header)
            page_path = info.doc_dir / Path(page_name)
            if page_path.exists():
                lines.append(f"- [{Path(header).stem}]({page_name}) - `{header}`")
            else:
                lines.append(f"- `{header}`")
        lines.append("")

    lines.append("## 相关文档")
    lines.append("")
    if info.relative == "XCEngine":
        lines.append("- [API 总索引](../main.md)")
        lines.append("- [API 文档重构状态](../_meta/rebuild-status.md)")
    else:
        lines.append(f"- [上级目录](../{info.doc_dir.parent.name}.md)")
        lines.append(f"- [API 总索引]({relative_link(index_path, API_ROOT / 'main.md')})")

    return "\n".join(lines).rstrip() + "\n"


def main() -> int:
    DOC_ROOT.mkdir(parents=True, exist_ok=True)
    infos = iter_include_dirs()
    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}")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())