企业官网建设流程全解析

• 机器学习
• 特征工程
• 数据增强

导读

本文以 imbalanced-learn 文档构建系统中的模板文件 doc/_templates/class.rst 为核心，拆解这个仅有 26 行的 Jinja2 模板如何驱动 Sphinx autosummary 为项目内数十个采样器类（SMOTE、RandomOverSampler、NearMiss 等）生成统一格式的 API 参考页。读完本文，你将理解 autosummary 模板的语法约定、与 numpydoc 及 sphinx-gallery 的分工协作，以及如何定制这类模板来改造整个项目的 API 文档排版。

class.rst 的定位：API 参考页的统一排版引擎

在 imbalanced-learn 仓库中，doc/_templates/class.rst不是一篇可读的文档正文，而是 Sphinx 在构建时用 Jinja2 渲染的页面骨架模板。它的作用是为每一个被autosummary指令收录的类，批量生成一张结构一致的参考页：类名标题、方法清单、示例回链、排版清理，全部由这一个模板统一完成。

该模板的调用方是 doc/references 目录下的各 API 参考文件。例如：

• doc/references/over_sampling.rst 中用:template: class.rst收录RandomOverSampler、SMOTE、SMOTENC、SMOTEN、ADASYN、BorderlineSMOTE、KMeansSMOTE、SVMSMOTE；
• doc/references/under_sampling.rst 中收录ClusterCentroids、NearMiss、TomekLinks等 10 个欠采样类；
• doc/references/combine.rst 中收录SMOTEENN、SMOTETomek；
• 此外 doc/references/ensemble.rst、doc/references/metrics.rst、doc/references/model_selection.rst、doc/references/keras.rst、doc/references/pipeline.rst、doc/references/miscellaneous.rst 也都引用该模板。

这些.rst文件统一挂在 doc/references/index.rst 的 toctree 之下，构成“API reference”整章。也就是说，整个 imbalanced-learn 的类级 API 文档，都是由这一个模板批量产出的。

模板语法逐段拆解

完整读取 doc/_templates/class.rst，其 26 行可按功能切成六段：

1. 页面标题与 reST 下划线约定

{{objname}} {{ underline }}==============

Sphinx autosummary 在渲染模板时会注入objname（被文档化的类名）与underline（与标题等长的下划线字符）。objname之后紧跟长度为标题文本长度的=，这是 reST 文档标题的标准写法——标题文本有多长，下划线就必须覆盖多长，否则 Sphinx 会报标题层级错误。模板用{{ underline }}而非固定长度的等号，正是为了保证任何长度的类名（如RepeatedEditedNearestNeighbours）都能生成合法标题。

2. 上下文切换指令

.. currentmodule:: {{ module }}

currentmodule指令把后续所有未限定的交叉引用（cross-reference）解析到当前模块命名空间。autosummary 注入的module值即被文档类的真实模块名，例如imblearn.over_sampling。它的作用是让页面内后续出现的~ClassName短引用无需写全限定名即可正确解析，同时避免 autodoc 在显示类名时带出冗长的模块前缀。

3. 核心指令：autoclass

.. autoclass:: {{ objname }}

autoclass是页面真正的内容来源。它触发 sphinx.ext.autodoc 读取类的 docstring，并按 numpydoc 的节序把类说明、参数、属性、方法等渲染成文档。在 doc/conf.py 中可以看到该项目的 autodoc 全局配置：

autodoc_default_options = { "members": True, "inherited-members": True, }

即默认展开所有成员并包含继承成员；numpydoc_show_class_members = False则关闭了 numpydoc 默认的类成员列表生成，把方法呈现的职责交给模板中下一段的autosummary块。

4. Methods 区块：rubric + autosummary 循环

{% block methods %} {% if methods %} .. rubric:: Methods .. autosummary:: {% for item in methods %} {% if '__init__' not in item %} ~{{ name }}.{{ item }} {% endif %} {%- endfor %} {% endif %} {% endblock %}

这是模板中最具"程序性"的部分，也是它区别于普通静态文档的关键：

• {% block methods %}：Jinja2 块定义，允许子模板在继承时覆写这一区域，为后续定制留出钩子；
• .. rubric:: Methods：在页面中插入一个无编号的小标题；
• .. autosummary::：其后缩进的每一行都会生成一个指向类方法的链接条目；
• {% for item in methods %}：遍历 autosummary 注入的类方法名列表；
• {% if '__init__' not in item %}：过滤掉__init__。因为__init__的签名已经在autoclass的参数区展示过，若在 Methods 列表里再列一遍会造成信息重复；
• ~{{ name }}.{{ item }}：~前缀让链接文本只显示方法短名（如fit_resample），而链接目标指向类名.方法名的完整对象。

正是这段循环，让SMOTE、NearMiss等每个类的页面都能自动、一致地列出其公开方法（fit、fit_resample、get_metadata_routing等），无需为每个类手写方法清单。

5. 示例回链

.. include:: {{module}}.{{objname}}.examples

这行指令把{{module}}.{{objname}}.examples文件的内容直接嵌入当前页面。这里的{{module}}中的点号会被 Sphinx 解析为路径分隔符。在构建阶段，这个文件由 sphinx-gallery 的backreferences（反向引用）机制自动生成：任何示例脚本中实例化了该类，就会被收集到references/generated/目录下的对应.examples文件中，最终在类文档页的 Methods 区块之后呈现"与本类相关的示例"列表。相关配置位于 doc/conf.py 的sphinx_gallery_conf：

sphinx_gallery_conf = { "doc_module": "imblearn", "backreferences_dir": os.path.join("references/generated"), "show_memory": True, "reference_url": {"imblearn": None}, }

backreferences_dir正是.examples文件的落盘目录。也就是说，类文档与示例图库之间通过模板这行 include 形成了自动双向链接，示例库更新后 API 文档无需人工维护。

6. 排版清理

.. raw:: html <div style='clear:both'></div>

sphinx-gallery 在文档页内嵌示例缩略图时常用浮动布局，这行clear:both的原始 HTML 确保页面底部内容不会被浮动的图片元素干扰错位。它是纯排版层面的收尾动作。

与 numpydoc_docstring.rst 的分工：docstring 如何被渲染

模板的另一半秘密藏在 doc/_templates/numpydoc_docstring.rst 中。这个文件同样位于doc/_templates，是 numpydoc 扩展在渲染每个对象的 docstring 时使用的子模板：

{{index}} {{summary}} {{extended_summary}} {{parameters}} {{returns}} {{yields}} {{other_parameters}} {{attributes}} {{raises}} {{warns}} {{warnings}} {{see_also}} {{notes}} {{references}} {{examples}} {{methods}}

它定义了 docstring 各节（摘要、参数、返回、属性、抛出异常、参见、示例、方法等）的固定渲染顺序。两套模板的分工非常清晰：

• numpydoc_docstring.rst处理单个对象 docstring 内部的节序；
• class.rst处理整个类页面骨架（标题、上下文、类主体、方法索引、示例回链）。

以SMOTE为例，其完整页面结构即为：页面标题 →currentmodule上下文 →autoclass（内部按 numpydoc_docstring 节序渲染类 docstring，包括sampling_strategy、k_neighbors等参数的详细说明与约束）→ Methods 方法索引 → 相关示例 → clear:both。imbalanced-learn 的BaseOverSampler._sampling_strategy_docstring（见 imblearn/over_sampling/base.py）正是通过这种机制注入到各个过采样器 docstring 中的共享参数说明。

与 function.rst 的对比：类页与函数页的分工

仓库中与class.rst配套的还有 doc/_templates/function.rst，结构高度相似：

{{objname}} {{ underline }}==================== .. currentmodule:: {{ module }} .. autofunction:: {{ objname }} .. include:: {{module}}.{{objname}}.examples .. raw:: html <div style='clear:both'></div>

两者唯一的结构差异在于主体指令：类模板用autoclass，函数模板用autofunction；类模板额外拥有 Methods 区块，函数模板则直接进入示例回链。这也解释了为什么函数页面（如 doc/references/metrics.rst 中收录的geometric_mean_score等指标函数）结构更简洁——函数没有方法索引可言。

完整工作链路：从 autosummary 指令到生成页面

把整条链路串起来，一次类 API 页面的生成过程如下：

1. 用户在 doc/references/under_sampling.rst 等文件中写.. autosummary::块，并通过:toctree: generated/与:template: class.rst指定输出目录与模板；
2. Sphinx 构建时，autosummary 扩展扫描列表中的类名，将其元信息（objname、module、underline、methods、name）注入 doc/_templates/class.rst 并渲染成.rst中间文件，写入generated/目录；
3. autoclass指令让 autodoc 依据 numpydoc 的 doc/_templates/numpydoc_docstring.rst 渲染类 docstring 的各节；
4. sphinx-gallery 构建完成后在references/generated/生成{{module}}.{{objname}}.examples反向引用文件，被模板的include指令嵌入；
5. 最终 HTML 页面通过 pydata_sphinx_theme 呈现（主题配置见 doc/conf.py 的html_theme）。

值得一提的是源码跳转功能：模板虽未直接写 linkcode 指令，但 doc/conf.py 通过 doc/sphinxext/github_link.py 的make_linkcode_resolve("imblearn", ...)注册了解析器，它用git rev-parse --short HEAD获取当前提交，配合inspect.getsourcefile定位对象源码文件与行号，从而在 autodoc 渲染的每个对象旁生成"查看源码"链接。这也意味着模板页面的信息最终可以追溯到 imblearn/over_sampling/base.py 等真实实现文件。

定制与扩展实践要点

基于对模板语法的分析，若要在 fork 中改造 imbalanced-learn 的 API 文档排版，可遵循以下要点：

• 保持标题与下划线用{{ objname }}/{{ underline }}组合，不要用固定长度等号，否则超长类名会破坏 reST 标题层级；
• 不要移除{% if '__init__' not in item %}过滤，否则__init__参数列表会在页面中出现两次；
• 利用{% block methods %}的 Jinja2 块机制做局部覆写，例如为 Methods 区块增加排序或分组逻辑，而不必整体复制模板；
• 如需给页面增加版本徽章、弃用提示或属性表格，可以在autoclass指令后新增自定义 reST 或 numpydoc 指令，页面结构按上述链路重新构建即可生效；
• .. include:: {{module}}.{{objname}}.examples不要随意删除，它是 API 文档与示例图库（examples 目录下的plot_*.py脚本）自动关联的唯一通道。

一句话总结：class.rst用 26 行模板换来了整个 imbalanced-learn API 文档的一致性——任何新增采样器类，只要在对应的references/*.rst的 autosummary 块中登记一行类名，完整的参考页（签名、参数、方法索引、示例回链）便会自动生成，这正是 Sphinx autosummary 模板化文档体系的典型范式。

• 机器学习
• 特征工程
• 数据增强