尧图网站建设 
PyMC 文档体系剖析Sphinx Autosummary class.rst 模板的结构、渲染机制与定制实战【免费下载链接】pymcBayesian Modeling and Probabilistic Programming in Python项目地址: https://gitcode.com/GitHub_Trending/py/pymc导读本文以 PyMC 仓库中驱动整棵 API 文档树的模板文件 docs/source/_templates/autosummary/class.rst 为切入点逐行拆解 Sphinxautosummary扩展的 Jinja2 模板语法、模板变量的来源与语义并结合 docs/source/conf.py、docs/source/api 目录下的 API 页面以及 PyMC 自定义的另一份 distribution.rst 模板讲清一个类如何从源码 docstring 变成文档页面的完整链路。读完你将掌握如何读懂并定制 Sphinx autosummary 模板、如何控制 Methods/Attributes 的自动生成与排版以及如何用make html在本地验证模板改动效果。一、模板在 PyMC 文档构建链中的位置PyMC 的文档系统基于 Sphinx 构建其构建配置集中在 docs/source/conf.py。与本文模板直接相关的配置如下extensions [ matplotlib.sphinxext.plot_directive, sphinx.ext.autodoc, sphinx.ext.autosummary, ... numpydoc, ... ] # Dont auto-generate summary for class members. numpydoc_show_class_members False autosummary_generate True autodoc_typehints none remove_from_toctrees [**/classmethods/*] templates_path [_templates]各配置项的作用对应关系为配置项值对模板的影响sphinx.ext.autosummary启用提供autosummary指令及模板渲染机制本文的 class.rst 正是它的自定义模板templates_path [_templates]相对 docs/source 的模板目录Sphinx 在此目录下查找autosummary/子目录中的自定义模板autosummary_generate True启用构建时自动扫描 API 页面的autosummary指令为每个条目生成占位 RST 文档numpydoc_show_class_members False关闭 numpydoc 的成员自动展开将类成员如何呈现的控制权完全交给 autosummary 模板避免与.. autoclass::的成员列表重复remove_from_toctrees [**/classmethods/*]匹配classmethods/子目录配合模板中的:toctree: classmethods让每个类方法生成独立小页面但不进入最终目录树详见下文第四节从这份配置可以确认class.rst 是 Sphinx autosummary 扩展为类类型条目objtype 为class准备的自定义渲染模板它在构建阶段被 Jinja2 引擎实例化输出一份完整的 RST 文档再交由 autodoc 解析生成最终 HTML。二、模板全文逐行解析class.rst全文仅 30 行但每一行都承担明确职责。以下按行号逐段拆解2.1 标题生成与模块上下文{{ fullname | escape | underline }}这是 Jinja2 表达式。fullname是 autosummary 注入的模板变量值为被渲染类的全限定名如pymc.distributions.continuous.Normal。表达式依次经过escape对特殊字符如、、做 HTML 转义保证标题安全underlineSphinx 提供的 Jinja2 过滤器根据标题字符串长度生成等长的下划线作为 reStructuredText 标题的下划线装饰线。即{{ fullname | escape | underline }}等价于把类全名渲染为一级标题并自动画线这是 Sphinx 生成 API 页面的标准标题写法。.. currentmodule:: {{ module }}module是类所属模块名如pymc.distributions.continuous。该指令将当前模块上下文设为该类所在模块使后续所有交叉引用解析都基于此模块写Normal即可被正确链接到该类。2.2 类主文档块.. autoclass:: {{ objname }}objname是类短名如Normal。autoclass指令会读取类的 docstring 渲染主要说明文字。值得注意由于conf.py中没有设置autoclass_content此处只渲染类本身的 docstring不合并__init__的文档。2.3 Methods 块带 Jinja2 条件与循环{% block methods %} {% if methods %} .. rubric:: Methods .. autosummary:: :toctree: classmethods {% for item in methods %} {{ objname }}.{{ item }} {%- endfor %} {% endif %} {% endblock %}这是模板中最核心、最值得研究的一段{% block methods %}/{% endblock %}Jinja2 模板块。允许后续通过{% extends %}继承本模板的子模板重写该区块自定义扩展入口。{% if methods %}当 autosummary 检测到该类存在可自动收集的公开方法列表通常由 numpydoc 从 docstring 的Methods小节解析时才渲染整个区块没有方法则整块省略避免生成空的 Methods 标题。.. rubric:: Methods生成一个不加目录条目的Methods小标题。.. autosummary:: :toctree: classmethods对内层条目再次启用 autosummary。:toctree: classmethods意味着每个方法都会生成一个独立的 RST 页面输出到当前文档所在目录的classmethods/子目录中。{% for item in methods %}{{ objname }}.{{ item }}{% endfor %}对方法名列表循环逐行输出类名.方法名的完整引用例如Normal.dist Normal.logp Normal.random2.4 Attributes 块{% block attributes %} {% if attributes %} .. rubric:: Attributes .. autosummary:: {% for item in attributes %} ~{{ name }}.{{ item }} {%- endfor %} {% endif %} {% endblock %}Attributes 块与 Methods 块结构对称但有两处关键差异没有:toctree:选项属性条目只生成一个内联的 autosummary 表格/列表不单独建页。这通常是因为属性多为简单常量或描述不值得为每个属性生成独立页面。引用前缀为~{{ name }}.{{ item }}~是 Sphinx 交叉引用的缩写显示修饰符——生成的链接文字只显示类名之后的部分即属性名本身不显示完整路径让列表更简洁。这里使用的变量是name而非objname两者通常等价都指被渲染类名区别详见第三节~前缀让列表项显示为属性名而非完整限定名。两个块的对比可以总结为一张表块触发条件输出指令toctree条目写法Methodsmethods非空.. rubric:: Methods.. autosummary:::toctree: classmethods每方法一页{{ objname }}.{{ item }}Attributesattributes非空.. rubric:: Attributes.. autosummary::无内联展示~{{ name }}.{{ item }}缩写显示三、模板变量来源与语义模板中出现的 5 个变量并非模板作者随意定义而是 Sphinx autosummary 扩展在收集条目时注入 Jinja2 上下文的。从本仓库的模板与 API 页面可以归纳其语义变量含义class.rst 中的使用位置fullname类的完整限定名含模块路径如pymc.distributions.continuous.Normal标题{{ fullname \| escape \| underline }}module类所属模块名如pymc.distributions.continuous.. currentmodule:: {{ module }}objname类短名如Normal.. autoclass:: {{ objname }}、Methods 条目前缀name与objname等价的类名变量模板作者用其渲染 Attributes 条目Attributes 条目前缀~{{ name }}.{{ item }}methods该类公开方法名列表来自 numpydoc docstring 的Methods小节条件判断与循环attributes该类公开属性名列表同样来自 docstring 的Attributes小节条件判断与循环这些方法/属性列表的来源可以在 PyMC 的实际类中印证。以 pymc/distributions/continuous.py 中的class Normal(Continuous)第 445 行为例其 docstring 遵循 numpydoc 规范包含Methods小节声明dist、logp、random等随机变量接口autosummary 正是从这类 docstring 解析出methods列表再由本模板渲染成Normal.dist、Normal.logp、Normal.random等条目。同理pymc/dims/distributions/scalar.py 中的class Normal(DimDistribution)第 100 行也会经由同一模板生成 dims 子系统的类文档。因此可以推断只要类的 docstring 按 numpydoc 规范书写了Methods/Attributes小节autosummary 就会自动收集并在渲染时注入methods/attributes列表模板中的{% if %}判断正是为了应对类没有方法或属性的边界情况。四、模板的产出效果与 toctree 机制4.1 从模板到最终页面的三步流水线整个渲染过程可概括为收集阶段构建时autosummary_generate True触发Sphinx 扫描 API 页面如 docs/source/api/distributions/continuous.rst中的autosummary指令为其中每个类名生成占位 RST渲染阶段对class类型的条目用本模板实例化。以continuous.rst中的Normal为例模板渲染结果大致为pymc.distributions.continuous.Normal .. currentmodule:: pymc.distributions.continuous .. autoclass:: Normal .. rubric:: Methods .. autosummary:: :toctree: classmethods Normal.dist Normal.logp Normal.random .. rubric:: Attributes .. autosummary:: ~Normal.attribute展开阶段autodoc 解析上一步的 RST生成类的完整文档 HTML其中:toctree: classmethods又触发为每个方法生成独立的classmethods/Normal.logp等页面。4.2 为什么remove_from_toctrees会指向classmethodsconf.py 中的remove_from_toctrees [**/classmethods/*]与本模板的:toctree: classmethods是成对设计方法子页面需要可被链接但不占据导航目录的地位——既允许用户从类页面跳转到单个方法页又不让几十上百个方法页污染侧边栏导航。这是 autosummary 定制中一个非常实用的技巧PyMC 直接把它固化在配置里。4.3 同目录下的兄弟模板distribution.rstclass.rst并非 PyMC 唯一的自定义模板。同一目录下还有 docs/source/_templates/distribution.rst它被 API 页面通过:template:选项显式指定使用例如 docs/source/api/distributions/continuous.rst 中.. autosummary:: :toctree: generated/ :template: distribution.rst AsymmetricLaplace Beta ...distribution.rst与class.rst的对比极具教学价值维度class.rst默认类模板distribution.rstPyMC 定制模板变量使用fullname、module、objname、name、methods、attributesfullname、module、objname、objtype分支处理仅针对类无objtype判断用{% if objtype class %}区分类与函数两种条目成员输出循环输出全部 Methods/Attributes只输出{{ objname }}.dist单个方法toctree 目录classmethods方法子页classmethodsdist 方法子页适用场景通用类文档概率分布类文档只关注.dist随机采样接口可见 PyMC 的策略是通用类走 autosummary 默认模板 class.rst 全量展示成员概率分布类走专用 distribution.rst 精简展示.dist入口。两者共享classmethods子目录命名也与remove_from_toctrees配置保持一致。五、实战如何验证与定制模板5.1 本地构建验证模板改动只有通过实际构建才能看到效果。PyMC 文档的本地构建方式记录在 docs/source/contributing/build_docs.md核心命令为# 在仓库根目录创建文档构建环境并安装本地 pymc可编辑模式 conda env create -f conda-envs/environment-docs.yml pip install -e . # 构建文档Makefile 位于仓库根目录 make clean make html其中make html通过sphinx-build执行完整构建会触发模板渲染make clean清理_build缓存与中间文件当调整 toctree 或模板结构后必须执行否则可能命中缓存看不到变化若只是微调单个页面可跳过make clean以加快迭代构建完成后make view会用 Pythonwebbrowser打开生成的静态网站预览。注意 docs/source/contributing/build_docs.md 明确提示文档构建在 Windows 上不受支持建议在 Docker 容器中进行仓库提供了 scripts/Dockerfile 与 scripts/dev.Dockerfile 可参考。5.2 常见定制方向基于前文的机制分析你可以针对本模板做如下扩展仅说明查看与配置方式不改动仓库文件重命名 Methods 标题直接修改.. rubric:: Methods文本即可例如改为.. rubric:: Public Methods让属性也生成独立页面给 Attributes 块的.. autosummary::增加:toctree: classattributes同时记得在 conf.py 的remove_from_toctrees中追加**/classattributes/*过滤特定方法在{% for item in methods %}循环内用{% if item not in [...] %}跳过内部方法控制条目排序Sphinx 按 docstring 中Methods小节的书写顺序注入列表调整 docstring 小节顺序即可改变渲染顺序为类定制专属模板参考distribution.rst的做法在 API 页的autosummary指令中通过:template:指定新模板文件模板文件需放在templates_path指向的目录即docs/source/_templates/下。5.3 一处易踩的坑{{ fullname | escape | underline }}中fullname是包含模块路径的全名若你希望标题只显示类短名可改用{{ objname | escape | underline }}但此时需确认.. currentmodule:: {{ module }}是否仍然存在否则autoclass的交叉引用会失效。fullname与objname的分工正是模板设计者留给定制者的第一个自由度。六、小结class.rst虽只有 30 行却是 PyMC 文档体系自动化的关键一环它把 numpydoc 风格的 docstring 与 Sphinx autosummary 的收集机制衔接起来通过 Jinja2 的条件、循环与块继承统一控制了全仓库数百个类的 Methods/Attributes 展示方式并与 conf.py 中的autosummary_generate、remove_from_toctrees等配置协同工作。理解了这份模板你就掌握了 Sphinx 自动 API 文档的核心定制入口——无论是为 PyMC 新增分布类文档还是在其他 Sphinx 项目中搭建同类文档体系都可以直接复用本文的机制分析。推荐结合以下仓库文件进一步研读模板本体docs/source/_templates/autosummary/class.rst、docs/source/_templates/distribution.rst构建配置docs/source/conf.pyAPI 页面入口docs/source/api.rst、docs/source/api/distributions/continuous.rst、docs/source/api/gp/cov.rst被渲染的类源码pymc/distributions/continuous.py、pymc/dims/distributions/scalar.py本地构建说明docs/source/contributing/build_docs.md【免费下载链接】pymcBayesian Modeling and Probabilistic Programming in Python项目地址: https://gitcode.com/GitHub_Trending/py/pymc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 PyMC 文档体系剖析：Sphinx Autosummary class.rst 模板的结构、渲染机制与定制实战
PyMC 文档体系剖析Sphinx Autosummary class.rst 模板的结构、渲染机制与定制实战【免费下载链接】pymcBayesian Modeling and Probabilistic Programming in Python项目地址: https://gitcode.com/GitHub_Trending/py/pymc导读本文以 PyMC 仓库中驱动整棵 API 文档树的模板文件 docs/source/_templates/autosummary/class.rst 为切入点逐行拆解 Sphinxautosummary扩展的 Jinja2 模板语法、模板变量的来源与语义并结合 docs/source/conf.py、docs/source/api 目录下的 API 页面以及 PyMC 自定义的另一份 distribution.rst 模板讲清一个类如何从源码 docstring 变成文档页面的完整链路。读完你将掌握如何读懂并定制 Sphinx autosummary 模板、如何控制 Methods/Attributes 的自动生成与排版以及如何用make html在本地验证模板改动效果。一、模板在 PyMC 文档构建链中的位置PyMC 的文档系统基于 Sphinx 构建其构建配置集中在 docs/source/conf.py。与本文模板直接相关的配置如下extensions [ matplotlib.sphinxext.plot_directive, sphinx.ext.autodoc, sphinx.ext.autosummary, ... numpydoc, ... ] # Dont auto-generate summary for class members. numpydoc_show_class_members False autosummary_generate True autodoc_typehints none remove_from_toctrees [**/classmethods/*] templates_path [_templates]各配置项的作用对应关系为配置项值对模板的影响sphinx.ext.autosummary启用提供autosummary指令及模板渲染机制本文的 class.rst 正是它的自定义模板templates_path [_templates]相对 docs/source 的模板目录Sphinx 在此目录下查找autosummary/子目录中的自定义模板autosummary_generate True启用构建时自动扫描 API 页面的autosummary指令为每个条目生成占位 RST 文档numpydoc_show_class_members False关闭 numpydoc 的成员自动展开将类成员如何呈现的控制权完全交给 autosummary 模板避免与.. autoclass::的成员列表重复remove_from_toctrees [**/classmethods/*]匹配classmethods/子目录配合模板中的:toctree: classmethods让每个类方法生成独立小页面但不进入最终目录树详见下文第四节从这份配置可以确认class.rst 是 Sphinx autosummary 扩展为类类型条目objtype 为class准备的自定义渲染模板它在构建阶段被 Jinja2 引擎实例化输出一份完整的 RST 文档再交由 autodoc 解析生成最终 HTML。二、模板全文逐行解析class.rst全文仅 30 行但每一行都承担明确职责。以下按行号逐段拆解2.1 标题生成与模块上下文{{ fullname | escape | underline }}这是 Jinja2 表达式。fullname是 autosummary 注入的模板变量值为被渲染类的全限定名如pymc.distributions.continuous.Normal。表达式依次经过escape对特殊字符如、、做 HTML 转义保证标题安全underlineSphinx 提供的 Jinja2 过滤器根据标题字符串长度生成等长的下划线作为 reStructuredText 标题的下划线装饰线。即{{ fullname | escape | underline }}等价于把类全名渲染为一级标题并自动画线这是 Sphinx 生成 API 页面的标准标题写法。.. currentmodule:: {{ module }}module是类所属模块名如pymc.distributions.continuous。该指令将当前模块上下文设为该类所在模块使后续所有交叉引用解析都基于此模块写Normal即可被正确链接到该类。2.2 类主文档块.. autoclass:: {{ objname }}objname是类短名如Normal。autoclass指令会读取类的 docstring 渲染主要说明文字。值得注意由于conf.py中没有设置autoclass_content此处只渲染类本身的 docstring不合并__init__的文档。2.3 Methods 块带 Jinja2 条件与循环{% block methods %} {% if methods %} .. rubric:: Methods .. autosummary:: :toctree: classmethods {% for item in methods %} {{ objname }}.{{ item }} {%- endfor %} {% endif %} {% endblock %}这是模板中最核心、最值得研究的一段{% block methods %}/{% endblock %}Jinja2 模板块。允许后续通过{% extends %}继承本模板的子模板重写该区块自定义扩展入口。{% if methods %}当 autosummary 检测到该类存在可自动收集的公开方法列表通常由 numpydoc 从 docstring 的Methods小节解析时才渲染整个区块没有方法则整块省略避免生成空的 Methods 标题。.. rubric:: Methods生成一个不加目录条目的Methods小标题。.. autosummary:: :toctree: classmethods对内层条目再次启用 autosummary。:toctree: classmethods意味着每个方法都会生成一个独立的 RST 页面输出到当前文档所在目录的classmethods/子目录中。{% for item in methods %}{{ objname }}.{{ item }}{% endfor %}对方法名列表循环逐行输出类名.方法名的完整引用例如Normal.dist Normal.logp Normal.random2.4 Attributes 块{% block attributes %} {% if attributes %} .. rubric:: Attributes .. autosummary:: {% for item in attributes %} ~{{ name }}.{{ item }} {%- endfor %} {% endif %} {% endblock %}Attributes 块与 Methods 块结构对称但有两处关键差异没有:toctree:选项属性条目只生成一个内联的 autosummary 表格/列表不单独建页。这通常是因为属性多为简单常量或描述不值得为每个属性生成独立页面。引用前缀为~{{ name }}.{{ item }}~是 Sphinx 交叉引用的缩写显示修饰符——生成的链接文字只显示类名之后的部分即属性名本身不显示完整路径让列表更简洁。这里使用的变量是name而非objname两者通常等价都指被渲染类名区别详见第三节~前缀让列表项显示为属性名而非完整限定名。两个块的对比可以总结为一张表块触发条件输出指令toctree条目写法Methodsmethods非空.. rubric:: Methods.. autosummary:::toctree: classmethods每方法一页{{ objname }}.{{ item }}Attributesattributes非空.. rubric:: Attributes.. autosummary::无内联展示~{{ name }}.{{ item }}缩写显示三、模板变量来源与语义模板中出现的 5 个变量并非模板作者随意定义而是 Sphinx autosummary 扩展在收集条目时注入 Jinja2 上下文的。从本仓库的模板与 API 页面可以归纳其语义变量含义class.rst 中的使用位置fullname类的完整限定名含模块路径如pymc.distributions.continuous.Normal标题{{ fullname \| escape \| underline }}module类所属模块名如pymc.distributions.continuous.. currentmodule:: {{ module }}objname类短名如Normal.. autoclass:: {{ objname }}、Methods 条目前缀name与objname等价的类名变量模板作者用其渲染 Attributes 条目Attributes 条目前缀~{{ name }}.{{ item }}methods该类公开方法名列表来自 numpydoc docstring 的Methods小节条件判断与循环attributes该类公开属性名列表同样来自 docstring 的Attributes小节条件判断与循环这些方法/属性列表的来源可以在 PyMC 的实际类中印证。以 pymc/distributions/continuous.py 中的class Normal(Continuous)第 445 行为例其 docstring 遵循 numpydoc 规范包含Methods小节声明dist、logp、random等随机变量接口autosummary 正是从这类 docstring 解析出methods列表再由本模板渲染成Normal.dist、Normal.logp、Normal.random等条目。同理pymc/dims/distributions/scalar.py 中的class Normal(DimDistribution)第 100 行也会经由同一模板生成 dims 子系统的类文档。因此可以推断只要类的 docstring 按 numpydoc 规范书写了Methods/Attributes小节autosummary 就会自动收集并在渲染时注入methods/attributes列表模板中的{% if %}判断正是为了应对类没有方法或属性的边界情况。四、模板的产出效果与 toctree 机制4.1 从模板到最终页面的三步流水线整个渲染过程可概括为收集阶段构建时autosummary_generate True触发Sphinx 扫描 API 页面如 docs/source/api/distributions/continuous.rst中的autosummary指令为其中每个类名生成占位 RST渲染阶段对class类型的条目用本模板实例化。以continuous.rst中的Normal为例模板渲染结果大致为pymc.distributions.continuous.Normal .. currentmodule:: pymc.distributions.continuous .. autoclass:: Normal .. rubric:: Methods .. autosummary:: :toctree: classmethods Normal.dist Normal.logp Normal.random .. rubric:: Attributes .. autosummary:: ~Normal.attribute展开阶段autodoc 解析上一步的 RST生成类的完整文档 HTML其中:toctree: classmethods又触发为每个方法生成独立的classmethods/Normal.logp等页面。4.2 为什么remove_from_toctrees会指向classmethodsconf.py 中的remove_from_toctrees [**/classmethods/*]与本模板的:toctree: classmethods是成对设计方法子页面需要可被链接但不占据导航目录的地位——既允许用户从类页面跳转到单个方法页又不让几十上百个方法页污染侧边栏导航。这是 autosummary 定制中一个非常实用的技巧PyMC 直接把它固化在配置里。4.3 同目录下的兄弟模板distribution.rstclass.rst并非 PyMC 唯一的自定义模板。同一目录下还有 docs/source/_templates/distribution.rst它被 API 页面通过:template:选项显式指定使用例如 docs/source/api/distributions/continuous.rst 中.. autosummary:: :toctree: generated/ :template: distribution.rst AsymmetricLaplace Beta ...distribution.rst与class.rst的对比极具教学价值维度class.rst默认类模板distribution.rstPyMC 定制模板变量使用fullname、module、objname、name、methods、attributesfullname、module、objname、objtype分支处理仅针对类无objtype判断用{% if objtype class %}区分类与函数两种条目成员输出循环输出全部 Methods/Attributes只输出{{ objname }}.dist单个方法toctree 目录classmethods方法子页classmethodsdist 方法子页适用场景通用类文档概率分布类文档只关注.dist随机采样接口可见 PyMC 的策略是通用类走 autosummary 默认模板 class.rst 全量展示成员概率分布类走专用 distribution.rst 精简展示.dist入口。两者共享classmethods子目录命名也与remove_from_toctrees配置保持一致。五、实战如何验证与定制模板5.1 本地构建验证模板改动只有通过实际构建才能看到效果。PyMC 文档的本地构建方式记录在 docs/source/contributing/build_docs.md核心命令为# 在仓库根目录创建文档构建环境并安装本地 pymc可编辑模式 conda env create -f conda-envs/environment-docs.yml pip install -e . # 构建文档Makefile 位于仓库根目录 make clean make html其中make html通过sphinx-build执行完整构建会触发模板渲染make clean清理_build缓存与中间文件当调整 toctree 或模板结构后必须执行否则可能命中缓存看不到变化若只是微调单个页面可跳过make clean以加快迭代构建完成后make view会用 Pythonwebbrowser打开生成的静态网站预览。注意 docs/source/contributing/build_docs.md 明确提示文档构建在 Windows 上不受支持建议在 Docker 容器中进行仓库提供了 scripts/Dockerfile 与 scripts/dev.Dockerfile 可参考。5.2 常见定制方向基于前文的机制分析你可以针对本模板做如下扩展仅说明查看与配置方式不改动仓库文件重命名 Methods 标题直接修改.. rubric:: Methods文本即可例如改为.. rubric:: Public Methods让属性也生成独立页面给 Attributes 块的.. autosummary::增加:toctree: classattributes同时记得在 conf.py 的remove_from_toctrees中追加**/classattributes/*过滤特定方法在{% for item in methods %}循环内用{% if item not in [...] %}跳过内部方法控制条目排序Sphinx 按 docstring 中Methods小节的书写顺序注入列表调整 docstring 小节顺序即可改变渲染顺序为类定制专属模板参考distribution.rst的做法在 API 页的autosummary指令中通过:template:指定新模板文件模板文件需放在templates_path指向的目录即docs/source/_templates/下。5.3 一处易踩的坑{{ fullname | escape | underline }}中fullname是包含模块路径的全名若你希望标题只显示类短名可改用{{ objname | escape | underline }}但此时需确认.. currentmodule:: {{ module }}是否仍然存在否则autoclass的交叉引用会失效。fullname与objname的分工正是模板设计者留给定制者的第一个自由度。六、小结class.rst虽只有 30 行却是 PyMC 文档体系自动化的关键一环它把 numpydoc 风格的 docstring 与 Sphinx autosummary 的收集机制衔接起来通过 Jinja2 的条件、循环与块继承统一控制了全仓库数百个类的 Methods/Attributes 展示方式并与 conf.py 中的autosummary_generate、remove_from_toctrees等配置协同工作。理解了这份模板你就掌握了 Sphinx 自动 API 文档的核心定制入口——无论是为 PyMC 新增分布类文档还是在其他 Sphinx 项目中搭建同类文档体系都可以直接复用本文的机制分析。推荐结合以下仓库文件进一步研读模板本体docs/source/_templates/autosummary/class.rst、docs/source/_templates/distribution.rst构建配置docs/source/conf.pyAPI 页面入口docs/source/api.rst、docs/source/api/distributions/continuous.rst、docs/source/api/gp/cov.rst被渲染的类源码pymc/distributions/continuous.py、pymc/dims/distributions/scalar.py本地构建说明docs/source/contributing/build_docs.md【免费下载链接】pymcBayesian Modeling and Probabilistic Programming in Python项目地址: https://gitcode.com/GitHub_Trending/py/pymc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考