企业官网建设流程全解析

• 人工智能
• 分布式训练
• 强化学习
• 任务调度
• 模型推理服务

导读

本文围绕 Ray 仓库中 doc/source/_templates/autosummary/class.rst 这一 Sphinx autosummary Jinja2 模板展开，说明 Ray 如何用它为数百个公开类自动生成 API 参考页面：短标签标题、currentmodule/autoclass指令、Methods 与 Attributes 分组的 autosummary 表格，以及针对 Sphinx 已知 bug 的规避策略。读完本文，你将掌握 Ray 文档体系中类 API 页面的生成链路、同目录下多个变体模板的适用场景，以及如何通过:template:选项在.rst/.md文档中灵活切换渲染方式。

一、模板在文档体系中的定位

Ray 的 API 参考文档采用「手写页面 + 自动生成 stub」的混合模式。开发者只需在文档中书写.. autosummary::表格列出类名，Sphinx 的sphinx.ext.autosummary扩展便会调用 class.rst 这类模板，为每个类生成独立的 stub 文件，再经 autodoc 渲染成完整的 API 页面。

• 模板目录：doc/source/_templates/autosummary/，共包含base.rst、class.rst、class_v2.rst及多个class_without_*变体。
• 扩展启用：sphinx.ext.autosummary、sphinx.ext.autodoc等配置在 doc/source/conf.py 的extensions列表中（见doc/source/conf.pyL58-L82）。
• 模板注册：conf.py通过from api_autogen import ...导入 doc/source/api_autogen.py，该模块把自定义 Jinja 过滤器注册到sphinx.ext.autosummary的FILTERS表中（doc/source/api_autogen.pyL102-L105），并定义autosummary_filename_map以规避ray.serve.deployment（装饰器）与ray.serve.Deployment（类）在不区分大小写文件系统上的文件名冲突（doc/source/api_autogen.pyL41-L48）。

二、class.rst 模板逐段解析

1. 头部注释：Sphinx issue 9884 的规避策略

模板开头的 Jinja2 注释记录了一个关键设计决策：

{# It's a known bug (https://github.com/sphinx-doc/sphinx/issues/9884) that autosummary will generate warning for inherited instance attributes. Those warnings will fail our build. For now, we don't autosummary classes with inherited instance attributes. To opt out, use `:template: autosummary/class_without_autosummary.rst` #}

要点：

• 已知问题：autosummary 对继承的实例属性（inherited instance attributes）会生成构建警告。
• Ray 的 CI 把这些警告视为构建失败，因此默认不为含继承实例属性的类启用 autosummary。
• 需要「退出」该默认行为时，在调用处改用:template: autosummary/class_without_autosummary.rst（该模板只展开 autoclass 成员，不再为方法/属性生成二级 autosummary stub）。

2. 短标签标题

{{ fullname.split('.')[-1] | escape | underline}}

• fullname是类的完整限定路径（如ray.data.Dataset.map）；
• split('.')[-1]只取叶子名称（map），使 API 侧边栏标签与页面 H1 简洁可读，而不是重复整条点分路径；
• escape防止特殊字符破坏 reStructuredText 结构；
• underline是 Sphinx 内置过滤器，把标题文本转为「标题 + 下划线装饰」的 RST 小节标题。

同样的短标签逻辑也出现在 base.rst 等模板中，属于 Ray 全套 autosummary 模板的统一约定。

3. currentmodule 与 autoclass 指令

.. currentmodule:: {{ module }} .. autoclass:: {{ objname }} :show-inheritance:

• currentmodule把当前模块设为module，使后续成员引用（如~类名.方法名）无需重复模块前缀；
• autoclass是 autodoc 的类文档指令，:show-inheritance:会在页面显示继承关系（基类列表）；
• 注意：模板本身不写:members:，成员由下面的 autosummary 表格按需展开——这正是它与class_without_autosummary.rst系列（后者显式写:members:）的本质区别。

4. Methods 分组与过滤

{% block methods %} {% if methods %} .. rubric:: {{ _('Methods') }} .. autosummary:: :nosignatures: :toctree: {% for item in methods %} {{ item | filter_out_undoc_class_members(name, module) }} {%- endfor %} {% endif %} {% endblock %}

• methods是 autosummary 注入模板的类方法列表，if methods保证无方法时不渲染空段落；
• .. rubric:: Methods生成“Methods”小标题（_()支持 i18n 翻译）；
• autosummary 表格使用:nosignatures:（隐藏函数签名）与:toctree:（为每个成员生成子页面并纳入目录树）；
• 关键过滤器filter_out_undoc_class_members(item, name, module)：只保留有 docstring 的公开方法。其实现见 doc/source/api_autogen.py L51-L57——通过import_module(module_name)拿到模块、getattr(cls, member_name)取成员，__doc__非空则返回~类名.成员名，否则返回空字符串（该行被跳过）。这保证了「无文档的方法绝不进入 API 页面」，是 Ray 文档质量门禁的一部分。

5. Attributes 分组

{% block attributes %} {% if attributes %} .. rubric:: {{ _('Attributes') }} .. autosummary:: :nosignatures: :toctree: {% for item in attributes %} ~{{ name }}.{{ item }} {%- endfor %} {% endif %} {% endblock %}

• 与 Methods 结构对称，属性同样以rubric + autosummary + toctree的方式呈现；
• 区别在于属性项直接写为~{{ name }}.{{ item }}（~前缀只显示最后一段，如Dataset.map中的map），未套用filter_out_undoc_class_members过滤器；
• name是类在调用处的短名，item是单个属性名，二者拼接成可解析的交叉引用。

三、模板变量一览

四、同目录变体模板与选择依据

doc/source/_templates/autosummary/ 下还存在多个配套模板，各有明确分工：

这些变体在仓库中的实际调用点（均为:template:引用）可直接佐证其用途：

• doc/source/data/api/_autogen.rst 使用class_v2.rst，配合api_autogen.py中get_api_groups/select_api_group过滤器按 API 分组渲染；
• doc/source/data/api/llm.rst 使用class_without_autosummary_noinheritance.rst；
• doc/source/serve/api/index.md 混合使用class_without_init_args.rst、class_without_autosummary.rst与autopydantic.rst；
• doc/source/cluster/running-applications/job-submission/jobs-package-ref.rst 使用class_without_autosummary.rst。

五、class_v2 与自定义过滤器：按 API 分组的方法表

class_v2.rst 是 class.rst 的进阶版本，展示了同一机制的扩展深度：

.. currentmodule:: {{ module }} {% if name | has_public_constructor(module) %} {{ name }} {{ '-' * name | length }} .. autoclass:: {{ objname }} {% endif %}

随后通过methods | get_api_groups(name, module)收集所有公开方法所属的分组集合，再对每个分组生成独立的 autosummary 表格（select_api_group过滤出属于该组的方法）。支撑它的四个自定义过滤器全部定义在 doc/source/api_autogen.py：

• has_public_constructor(class_name, module_name)（L60-L62）：用_is_public_api判断类构造器是否标注为PublicAPI，只有公开才渲染类名与 autoclass；
• get_api_groups(method_names, class_name, module_name)（L65-L75）：遍历公开方法，收集其_annotated_api_group属性，返回排序后的分组集合；
• select_api_group(method_names, class_name, module_name, api_group)（L78-L85）：筛选出同时满足「公开 API」且属于指定分组的成员列表；
• _is_public_api(obj)（L88-L92）：读取_annotated_type并判断其值是否为PublicAPI，这是 Ray 用注解（annotation）驱动文档可见性的核心机制。

由此可见，Ray 的 API 文档并非「把所有成员一股脑列出」，而是以@PublicAPI注解与_annotated_api_group分组标注为准绳，动态决定哪些方法、按什么分组出现在参考手册中。

六、从模板到页面：生成链路与构建集成

1. stub 生成入口

doc/source/api_autogen.py 的generate_api_stubs(srcdir, app)（L129 起）是 stub 生成入口：

• 遍历AUTOGEN_FILES（doc/source/api_autogen.py顶部定义的手写页面列表）；
• 无活动 Sphinx 应用时，用_build_standalone_app构造DummyApplication，把doc/source/_templates加入模板路径（保证:template:引用可解析），并挂载autosummary_filename_map（L108-L126）；
• 生成失败时抛出RuntimeError，以「响亮失败」替代原先的静默try/except——坏掉的 autosummary 源或模板会直接让构建失败，而不是生成空 stub 被一致性检查误认为「无事可做」（L139-L146）。

2. conf.py 侧的集成点

• doc/source/conf.pyL29-L35：import api_autogen即完成过滤器注册；
• L801：autosummary_filename_map = AUTOSUMMARY_FILENAME_MAP注入文件名映射；
• llms_txt_exclude（doc/source/conf.pyL118 起）中把_templates/*、*doc/*等自动生成的 API 子页排除出 llms-full.txt 语料，避免 autodoc 样板内容淹没 agent 可读的全文索引——模板生成的页面也因此对 LLM/Agent 检索保持「按需拉取」而非「全量灌入」。

七、实战：如何在文档中选用正确的模板

在任意 API 参考页中，autosummary表格会按默认规则选用class.rst；如需切换模板，在 autosummary 指令上附加:template:即可：

.. autosummary:: :toctree: doc :template: autosummary/class_v2.rst ray.data.Dataset ray.data.Dataset.map

选择建议：

• 类含继承实例属性、且构建期会出现 issue 9884 相关警告时，改用autosummary/class_without_autosummary.rst；
• 需要隐藏基类信息时，使用autosummary/class_without_autosummary_noinheritance.rst（参考 doc/source/data/api/llm.rst）；
• 需要在页面内联展示全部成员而不生成二级 stub、也不建索引时，使用autosummary/class_without_autosummary_noindex.rst；
• 需要在同一个类下按_annotated_api_group分组展示方法时，使用autosummary/class_v2.rst（参考 doc/source/data/api/_autogen.rst）。

八、小结

class.rst是 Ray 文档系统中「类 API 页面」的默认渲染模板：它用短标签保证可读性，用currentmodule/autoclass/autosummary指令串联生成链路，用filter_out_undoc_class_members过滤器执行「无文档即不展示」的质量门禁，并围绕 Sphinx issue 9884 设计了一整套class_without_*变体供开发者按需切换。理解这一模板体系，不仅有助于在 Ray 中新增 API 文档时选择正确的渲染方式，也适用于任何基于 Sphinx autosummary + 自定义 Jinja 过滤器的大型项目文档工程实践。

• 人工智能
• 分布式训练
• 强化学习
• 任务调度
• 模型推理服务