OpenUSD 文档工程指南Sphinx 用户文档的撰写规范、本地构建与 Schema 用户文档自动化生成【免费下载链接】OpenUSDUniversal Scene Description项目地址: https://gitcode.com/GitHub_Trending/ope/OpenUSD本文基于 OpenUSD 仓库中的 docs/README.md 撰写系统讲解该项目的文档工程体系如何用 Sphinx 构建用户文档、如何遵循 USD 推荐的 reStructuredText 样式规范撰写文档、如何通过 doxylink 打通用户文档与 Doxygen API 文档的交叉引用以及如何用genSchemaDocs.py从 USD Schema 自动生成 Schema 用户文档。读完本文你将能够独立配置 Sphinx 构建环境、按 USD 规范编写文档源码并为自定义 Schema 一键生成配套的 Sphinx 文档。一、USD 文档体系概览Sphinx 与 Doxygen 双引擎OpenUSDUniversal Scene Description的文档分为两条独立的生产线用户文档User Documentation使用 Sphinx 构建。源码以reStructuredTextrst为主同时也允许使用MyST Markdown编写最终渲染为 HTML 并发布到 openusd.org 的 release 站点。API 文档API Documentation使用Doxygen生成为 C 类、函数提供参考手册。两者的桥梁是 Sphinx 的Doxylink扩展用户文档通过自定义角色:usdcpp:链接到 Doxygen 生成的 API 文档页面从而在教程、指南中实现概念讲解 API 参考的无缝跳转。1.1 USD 的 Sphinx 构建依赖扩展根据 docs/README.md 与 docs/conf.py 中extensions列表的实际配置USD 文档构建依赖以下扩展扩展用途sphinx.ext.autosectionlabel自动为每个章节生成可引用标签配合autosectionlabel_prefix_document True以文档名为前缀sphinxcontrib.doxylink读取 Doxygen 生成的 .tag 文件实现:usdcpp:角色myst_parser解析 MyST Markdown 语法sphinxcontrib.datatemplates数据模板扩展sphinx_designSphinx Design 组件如 admonition 提示框、网格卡片主题方面docs/conf.py 使用sphinx_rtd_themeReadTheDocs 主题并定制了navigation_depth: 4、style_nav_header_background: #606060等选项html_css_files挂载了自定义样式 docs/_static/css/pxr_custom.csshtml_js_files挂载了版本切换脚本 docs/_static/js/versions.js。二、本地环境搭建安装 Sphinx 与必需扩展注意仓库的构建脚本 build_scripts/build_usd.py 只负责构建 USD 的 Doxygen API 文档不构建 Sphinx 文档项目有意避免在核心构建中引入 Sphinx 及其依赖包因此完整文档需要手动构建。2.1 安装 Sphinx 与扩展在已安装 Python 的前提下用 pip 一次性安装 Sphinx 及全部扩展pip3 install --user sphinx sphinx-rtd-theme sphinx_design sphinxcontrib-doxylink myst-parser2.2 配置环境变量安装完成后把 Sphinx 可执行文件加入 PATH并确保 Python 能找到本地安装的包以 csh/tcsh 为例写入~/.cshrc或对应 shell 配置文件# 修改配置后需执行 rehash 或新开一个 shell 使其生效 setenv PATH $HOME/.local/bin:$PATH # Linux 下 Python 还需要找到本地安装目录 setenv PYTHONPATH $HOME/.local:$PYTHONPATH从 docs/conf.py 的GetUSDVersion()函数可以看到Sphinx 构建时还会读取 cmake/defaults/Version.cmake 中的PXR_MAJOR_VERSION/PXR_MINOR_VERSION/PXR_PATCH_VERSION来确定文档版本号version {minor}.{patch}并自动将两位版本号补零如21.8→21.08确保版本信息与仓库实际发布版本一致。三、USD Sphinx 样式指南USD 文档有一套明确的撰写规范推荐所有编辑者遵循。以下 rst 指令同样可以在 MyST Markdown 中使用语法略有不同。3.1 交叉引用:ref:与:doc:跨文档章节链接使用:ref:角色目标为其他文档中的章节标题。例如链接到glossary.rst中的 API Schema 条目:ref:glossary:API Schema :ref:Custom Link Text glossary:API Schema页内链接仅此一种情况必须使用尾随下划线语法Custom Link Text glossary:API Schema_链接到其他文档使用:doc:角色。例如链接到tut_helloworld.rst这个 Hello World 教程:doc:tut_helloworld :doc:Custom Link Text tut_helloworld在 docs/conf.py 中设置了autosectionlabel_prefix_document True这正是:ref:glossary:API Schema 这种文档名:章节名语法能够工作的前提。3.2 链接 Doxygen API 文档:usdcpp:角色:usdcpp:是使用 doxylink 扩展创建的自定义角色用于链接指定函数或类的 Doxygen API 文档。例如链接UsdStage的 API 文档:usdcpp:UsdStage :usdcpp:Custom Link Text UsdStage其底层实现见 docs/conf.pydoxylink配置项把角色名usdcpp映射到(doxygenTagFile, doxygenPrefix)二元组Sphinx 据此把:usdcpp:目标解析为对应的 Doxygen HTML 页面。3.3 标题层级约定为了与 ReadTheDocs 主题的导航栏良好配合标题必须遵循以下符号约定H1–H6级别符号说明H1#且带顶线overline文档主标题H2*且带顶线overline一级章节H3二级章节H4-三级章节H5^四级章节H6五级章节3.4 code-block 指令与语法高亮code-block指令通过参数指定语法高亮语言USD 文档中常用取值包括python、cpp、usd、usda、none。例如.. code-block:: python from pxr import Usd, UsdGeom stage Usd.Stage.CreateNew(HelloWorld.usda) xformPrim UsdGeom.Xform.Define(stage, /hello) spherePrim UsdGeom.Sphere.Define(stage, /hello/world) stage.GetRootLayer().Save()3.5 内联格式快速参考与自定义角色USD 文档定义了一套内联格式写法并额外提供了若干语义化角色。其定义集中在 docs/rolesAndUtils.rst注意角色名必须全小写写法渲染效果说明*italics*italics斜体**bold**bold粗体:bi:bolditalicsbolditalics粗斜体rolesAndUtils 中通过.. role:: bi定义:mono:monospacemonospace等宽字体:sdfpath:/World/anim/chars/Bob场景描述路径如 prim 路径:filename:文件名/资源如extras/usd/tutorials/helloWorld:python:行内 Python 代码如UsdStage.Open:cpp:行内 C 代码指不对应 Doxygen API 条目的代码如UsdStage::Open:code:语言无关的行内代码如Get()或不属于上述语言的代码这些角色在 docs/rolesAndUtils.rst 中通过.. role::指令声明并绑定了mono、sdfpath等 CSS 类保证全站格式统一。四、本地构建用户文档4.1 拉取 Doxygen API 文档可选但推荐要在用户文档中启用指向 Doxygen API 文档的链接需要在运行sphinx-build前设置两个环境变量USD_DOXYGEN_TAG_FILEDoxygen 构建生成的.tag文件路径。Sphinx 读取该文件以确定某个类或函数对应的 HTML 文档页面。默认情况下USD 构建会把该文件安装到USD_INSTALL_ROOT/docs/USD.tag。USD_DOXYGEN_PREFIXDoxygen HTML 文件所在目录的URI。Sphinx 会用它作为所有 Doxygen HTML 链接的前缀。默认安装位置为USD_INSTALL_ROOT/docs/doxy_html。例如对于一个未由 Web 服务器托管的 USD 安装USD_INSTALL_ROOT为安装根目录setenv USD_DOXYGEN_TAG_FILE USD_INSTALL_ROOT/docs/USD.tag setenv USD_DOXYGEN_PREFIX file://USD_INSTALL_ROOT/docs/doxy_html若未设置这两个变量用户文档依然可以构建成功但 Sphinx 会输出一些警告且文档中指向 API 文档的链接不会出现。这一行为在 docs/conf.py 中有明确实现两个变量缺失时分别打印warning级别的日志并将对应配置置为空字符串。4.2 执行构建进入包含本 README 与 rst 源码文件的目录即 docs/执行sphinx-build . /tmp/usddocsSphinx 会跟踪已变更的文件因此后续构建会比首次构建快。构建的入口文档由master_doc index指定为 docs/index.rst。五、从 USD Schema 自动生成 Schema 用户文档这是 USD 文档工程中最具特色的环节Schema 的用户文档不再是手工维护的孤立页面而是以customData元数据的形式内嵌在.usda文件中再由genSchemaDocs.py一键生成 Sphinx 内容。这样既保证了文档与 Schema 定义同源、不漂移又让 DCC 工具 UI 可以复用同一份简介文本。5.1 生成工具genSchemaDocs.py工具入口为 docs/python/genSchemaDocs.py。从源码_GetArgs()看它接受两个位置参数和一个开关python python/genSchemaDocs.py [schemaUserDocPath] [sphinxOutputPath] [-t]参数含义默认值schemaUserDocPath源 USD 文件schemaUserDoc.usda也接受直接内嵌 customData 的schema.usda或其所在目录./schemaUserDoc.usdasphinxOutputPath生成的 Markdown 输出目录.-t/--sphinxTocFile额外生成一个示例用的 Sphinx 目录TOC文件关闭工具的核心流程_ProcessSchemaDocs()为加载schemaUserDoc.usda组合成 stage → 从/GLOBALprim 读取libraryName与userDocTitle→ 遍历根层 Schema 类从 prim 的customData中提取userDoc→ 通过UsdClass.GetProperties()拿到包含继承在内的全部属性 → 为每个属性生成独立章节。值得注意的细节包括生成的每个 Schema 类和属性都会自动添加 Sphinx 标签格式为schema 名_属性名见_SchemaDocMarkdownGenerator.WriteProperty标签须位于标题之前才能被 Sphinx 用作锚点。属性章节会输出USD 类型**USD type**: \float若 Schema 定义了 fallback 值还会输出 **Fallback value**Fallback value: 1.0关系relationship类型会被标注为(relationship)。属性先列出非继承属性再按继承层级顺序列出继承属性## Inherited Properties (父类名)。工具会扫描 Markdown 中的alt与 Myst 风格{image} path两种图片引用正则见_GetResourceFilesFromMarkdownString把本地资源文件一并拷贝到输出目录。生成的每个 Markdown 文件头部带有% WARNING: THIS FILE IS GENERATED BY genSchemaDocs. DO NOT EDIT.注释提醒不要手工编辑生成产物。入口处会设置USD_DISABLE_PRIM_DEFINITIONS_FOR_USDGENSCHEMA1环境变量避免加载generatedSchema.usda确保脚本只依据当前加载的schema.usda/schemaUserDoc.usda信息处理。5.2 编写 Schema 用户文档源文件编写流程分三步第一步在schema.usda所在目录下创建userDoc子目录。第二步在userDoc目录中为 Schema 编写 overview 指南 Markdown 文件MyST Markdown 格式本地图片也放入该目录。第三步在userDoc目录中创建或更新schemaUserDoc.usda为 Schema 类与属性提供参考文档。该文件应sublayer你的schema.usda以获得正确的 Schema 继承结构与属性 fallback 值以over形式为每个要写文档的 Schema 类与属性添加userDoc与userDocBrief两条customData字符串元数据userDoc用于生成 Sphinx 输出格式为 MyST MarkdownuserDocBrief不用于 Sphinx 输出而是用于 DCC 工具 UI 中展示的简短简介。一个完整的类与属性文档 over 示例如下over SchemaClass SchemaClass ( customData { string userDocBrief A short sentence or two describing the schema. string userDoc A longer set of paragraphs describing the schema in detail. Use Markdown format to include images, links, etc. Use Myst Markdown to add Sphinx directives like references and labels. } ) { asset schemaAssetProperty ( customData { string userDocBrief A short sentence or two describing the property. string userDoc A longer set of paragraphs describing the property in detail, again using Markdown and Sphinx directives as needed. } ) }此外schemaUserDoc.usda还必须提供一个GLOBALprim通过 customData 声明 Schema 域名称libraryName以及生成文档目录页的短标题userDocTitle。例如 usdVol 的 GLOBAL overover GLOBAL ( customData { string libraryName usdVol string userDocTitle Volumes } ) { }5.3 运行生成命令在仓库根目录执行README 中给出的示例路径为docs/下运行此处给出仓库根目录等价写法以 usdVol 为例将其 Sphinx 文件生成到docs/user_guides/schemas/usdVol/python docs/python/genSchemaDocs.py pxr/usd/usdVol/userDoc docs/user_guides/schemas -tREADME 原文示例中源目录写作../pxr/usd/usdVol/userDocs实际仓库中该目录名为userDoc见 pxr/usd/usdVol/userDoc/使用时以实际目录名为准。该命令会解析pxr/usd/usdVol/userDoc中的内容在docs/user_guides/schemas/usdVol/下生成每个 Schema 类一个.md文件如Volume.md、OpenVDBAsset.md、VolumeFieldAsset.md等拷贝 overview 指南overview.md与其中的本地图片如volExample.png生成usdVol_toc.rst目录文件可被任何 Sphinx RST 文件如 docs/user_guides/schemas/index.rst以.. include::或 toctree 方式引入。目前 docs/user_guides/schemas/ 下已发布的各 Schema 文档均是由genSchemaDocs.py生成可视为该工具的标准产物样例。5.4 编写注意事项来自 README 的实战经验多行文档字符串不要有前导空白。生成过程不会剥离前导空白否则会破坏 codeblock 等内容的缩进多余空白会原样出现在生成的 HTML 中。不要在schemaUserDoc.usda中添加自定义 Markdown 标题如# Title。生成工具会自动为类与属性创建标题和 Sphinx 标签额外的标题可能导致输出混乱也不需要为 Schema 类与属性手动添加 RST 标签。生成工具会自动为类与属性添加 Sphinx 标签格式为schema 名_属性名供其他文档交叉引用。在 overview 指南 Markdown 中可以自由为需要被schemaUserDoc.usda内容链接的章节添加标签MyST Markdown 的写法是在单独一行写(标签名)。六、仓库中的完整范例usdVol 的 Schema 用户文档pxr/usd/usdVol/userDoc/ 是 README 推荐的参考实例包含三个文件schemaUserDoc.usdasublayer 了../schema.usda即 pxr/usd/usdVol/schema.usda以 over 形式为Volume、VolumeFieldBase、VolumeFieldAsset、OpenVDBAsset、Field3DAsset、ParticleField及一系列 ParticleField 相关 applied schema 撰写文档。例如VolumeFieldAsset.filePath属性文档详细说明了该属性可随时间动画多数体素格式仅代表单个时间采样但目前不支持$F之类的模式替换OpenVDBAsset.fieldClass文档则映射到 OpenVDB 的GRID_LEVEL_SET、GRID_FOG_VOLUME、GRID_STAGGERED、GRID_UNKNOWN四类。overview.md以 MyST Markdown 编写的概览指南包含 Working With Volumes、Working With Fields、Working With Particle Fields 三个带标签如(usdVol_working_with_volumes)的章节并有{code-block} usda、{admonition}等 Myst 指令的使用示范。volExample.pngoverview 中引用的本地示例图片。对应的生成产物位于 docs/user_guides/schemas/usdVol/包括Volume.md、OpenVDBAsset.md、ParticleField3DGaussianSplat.md等 19 个 Schema 文档、overview.md与usdVol_toc.rst。对照源文件与产物可以直观理解userDoc元数据是如何被转换为带有(label)锚点、**USD type**、**Fallback value**等结构化内容的 Sphinx 文档的。七、总结USD 文档工程的完整工作流回顾全文OpenUSD 的文档工程可以归纳为一条清晰的生产流水线安装工具链pip3 install --user sphinx sphinx-rtd-theme sphinx_design sphinxcontrib-doxylink myst-parser并配置PATH/PYTHONPATH编写用户文档在 docs/ 下用 rst或 MyST Markdown按 USD 样式规范撰写遵循标题符号约定、使用:ref:/:doc:/:usdcpp:交叉引用与:sdfpath:、:filename:、:python:等语义化角色配置 Doxygen 桥接设置USD_DOXYGEN_TAG_FILE与USD_DOXYGEN_PREFIX使用户文档中的:usdcpp:链接生效为 Schema 编写文档在schema.usda旁创建userDoc目录编写schemaUserDoc.usda含GLOBALprim 与userDoc/userDocBriefcustomData及 overview 指南生成 Schema 文档运行python docs/python/genSchemaDocs.py userDoc目录 输出目录 -t得到 Markdown 产物与*_toc.rst目录文件构建发布在 docs/ 下执行sphinx-build . 输出目录生成最终 HTML。这套体系的核心价值在于Schema 文档与 Schema 定义同源共生——修改 Schema 属性时可在同一.usda中同步更新文档既降低了文档漂移风险又通过自动生成的 Sphinx 标签实现了全站交叉引用的稳定性。【免费下载链接】OpenUSDUniversal Scene Description项目地址: https://gitcode.com/GitHub_Trending/ope/OpenUSD创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
