人工智能分布式训练强化学习任务调度模型推理服务【免费下载链接】rayRay is an AI compute engine. Ray consists of a core distributed runtime and a set of AI Libraries for accelerating ML workloads.项目地址https://gitcode.com/gh_mirrors/ra/ray点击查看免费下载导读本文围绕 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 注释记录了一个关键设计决策{# Its 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 dont 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.mapsplit(.)[-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是单个属性名二者拼接成可解析的交叉引用。三、模板变量一览变量含义模板中的用法fullname对象的完整限定名如ray.data.Dataset.mapfullname.split(.)[-1]生成短标签module对象所在模块名.. currentmodule::objname对象名称类名无模块前缀.. autoclass::name调用处的对象短名~{{ name }}.{{ item }}属性引用methods类方法名列表for循环 过滤后生成 Methods 表格attributes类属性名列表for循环生成 Attributes 表格四、同目录变体模板与选择依据doc/source/_templates/autosummary/ 下还存在多个配套模板各有明确分工模板核心差异典型用途base.rstauto{{ objtype }}通配任意对象类型只有短标签 currentmodule autodoc 指令函数、异常等非类对象的通用模板class.rstautoclass Methods/Attributes 分组 无文档成员过滤默认的类 API 页面模板class_v2.rst按_annotated_api_group对方法分组建表:toctree: doc仅当类有公开构造器时才渲染需要按 API 分组展示的类如 Data APIclass_without_autosummary.rstautoclass 直接:members: :show-inheritance:不再为成员生成二级 stub退出 issue 9884 规避策略、含继承实例属性的类class_without_autosummary_noindex.rst在上者基础上加:noindex:需要内联展示但禁止重复建索引的类class_without_autosummary_noinheritance.rst:members:但不显示继承关系不希望暴露基类信息如 LLM API 数据类class_without_init_args.rstautoclass:: {{ objname }}()显式带括号、:members:Serve API 中强调构造器调用形式的类这些变体在仓库中的实际调用点均为: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.rstdoc/source/serve/api/index.md 混合使用class_without_init_args.rst、class_without_autosummary.rst与autopydantic.rstdoc/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.pyhas_public_constructor(class_name, module_name)L60-L62用_is_public_api判断类构造器是否标注为PublicAPI只有公开才渲染类名与 autoclassget_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_FILESdoc/source/api_autogen.py顶部定义的手写页面列表无活动 Sphinx 应用时用_build_standalone_app构造DummyApplication把doc/source/_templates加入模板路径保证:template:引用可解析并挂载autosummary_filename_mapL108-L126生成失败时抛出RuntimeError以「响亮失败」替代原先的静默try/except——坏掉的 autosummary 源或模板会直接让构建失败而不是生成空 stub 被一致性检查误认为「无事可做」L139-L146。2. conf.py 侧的集成点doc/source/conf.pyL29-L35import api_autogen即完成过滤器注册L801autosummary_filename_map AUTOSUMMARY_FILENAME_MAP注入文件名映射llms_txt_excludedoc/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 过滤器的大型项目文档工程实践。赞分享人工智能分布式训练强化学习任务调度模型推理服务【免费下载链接】rayRay is an AI compute engine. Ray consists of a core distributed runtime and a set of AI Libraries for accelerating ML workloads.项目地址https://gitcode.com/gh_mirrors/ra/ray点击查看免费下载相关推荐深入解析 yfinance 文档体系Sphinx autosummary 类模板 class.rst 的作用与定制指南深入解析 yfinance 文档体系Sphinx autosummary 类模板 class.rst 的作用与定制指南 导读 在 yfinance 这个Py数据分析金融科技CuPy 文档系统解析Sphinx autosummary 的 class.rst 模板原理与定制指南CuPy 文档系统解析Sphinx autosummary 的 class.rst 模板原理与定制指南 导读 本文以 CuPy 仓库中的 docs/sourc科学计算高性能计算Warp API 文档生成探秘Sphinx autosummary 类模板 class.rst 的结构解析与定制实践Warp API 文档生成探秘Sphinx autosummary 类模板 class.rst 的结构解析与定制实践 Warp 的官方 API 参考文档涵盖高性能计算物理引擎图形学机器人创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
人工智能分布式训练强化学习任务调度模型推理服务【免费下载链接】rayRay is an AI compute engine. Ray consists of a core distributed runtime and a set of AI Libraries for accelerating ML workloads.项目地址https://gitcode.com/gh_mirrors/ra/ray点击查看免费下载导读本文围绕 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 注释记录了一个关键设计决策{# Its 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 dont 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.mapsplit(.)[-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是单个属性名二者拼接成可解析的交叉引用。三、模板变量一览变量含义模板中的用法fullname对象的完整限定名如ray.data.Dataset.mapfullname.split(.)[-1]生成短标签module对象所在模块名.. currentmodule::objname对象名称类名无模块前缀.. autoclass::name调用处的对象短名~{{ name }}.{{ item }}属性引用methods类方法名列表for循环 过滤后生成 Methods 表格attributes类属性名列表for循环生成 Attributes 表格四、同目录变体模板与选择依据doc/source/_templates/autosummary/ 下还存在多个配套模板各有明确分工模板核心差异典型用途base.rstauto{{ objtype }}通配任意对象类型只有短标签 currentmodule autodoc 指令函数、异常等非类对象的通用模板class.rstautoclass Methods/Attributes 分组 无文档成员过滤默认的类 API 页面模板class_v2.rst按_annotated_api_group对方法分组建表:toctree: doc仅当类有公开构造器时才渲染需要按 API 分组展示的类如 Data APIclass_without_autosummary.rstautoclass 直接:members: :show-inheritance:不再为成员生成二级 stub退出 issue 9884 规避策略、含继承实例属性的类class_without_autosummary_noindex.rst在上者基础上加:noindex:需要内联展示但禁止重复建索引的类class_without_autosummary_noinheritance.rst:members:但不显示继承关系不希望暴露基类信息如 LLM API 数据类class_without_init_args.rstautoclass:: {{ objname }}()显式带括号、:members:Serve API 中强调构造器调用形式的类这些变体在仓库中的实际调用点均为: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.rstdoc/source/serve/api/index.md 混合使用class_without_init_args.rst、class_without_autosummary.rst与autopydantic.rstdoc/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.pyhas_public_constructor(class_name, module_name)L60-L62用_is_public_api判断类构造器是否标注为PublicAPI只有公开才渲染类名与 autoclassget_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_FILESdoc/source/api_autogen.py顶部定义的手写页面列表无活动 Sphinx 应用时用_build_standalone_app构造DummyApplication把doc/source/_templates加入模板路径保证:template:引用可解析并挂载autosummary_filename_mapL108-L126生成失败时抛出RuntimeError以「响亮失败」替代原先的静默try/except——坏掉的 autosummary 源或模板会直接让构建失败而不是生成空 stub 被一致性检查误认为「无事可做」L139-L146。2. conf.py 侧的集成点doc/source/conf.pyL29-L35import api_autogen即完成过滤器注册L801autosummary_filename_map AUTOSUMMARY_FILENAME_MAP注入文件名映射llms_txt_excludedoc/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 过滤器的大型项目文档工程实践。赞分享人工智能分布式训练强化学习任务调度模型推理服务【免费下载链接】rayRay is an AI compute engine. Ray consists of a core distributed runtime and a set of AI Libraries for accelerating ML workloads.项目地址https://gitcode.com/gh_mirrors/ra/ray点击查看免费下载相关推荐深入解析 yfinance 文档体系Sphinx autosummary 类模板 class.rst 的作用与定制指南深入解析 yfinance 文档体系Sphinx autosummary 类模板 class.rst 的作用与定制指南 导读 在 yfinance 这个Py数据分析金融科技CuPy 文档系统解析Sphinx autosummary 的 class.rst 模板原理与定制指南CuPy 文档系统解析Sphinx autosummary 的 class.rst 模板原理与定制指南 导读 本文以 CuPy 仓库中的 docs/sourc科学计算高性能计算Warp API 文档生成探秘Sphinx autosummary 类模板 class.rst 的结构解析与定制实践Warp API 文档生成探秘Sphinx autosummary 类模板 class.rst 的结构解析与定制实践 Warp 的官方 API 参考文档涵盖高性能计算物理引擎图形学机器人创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
