如何通过替换修改Sphinx autoclass指令的目标类？

这问题我之前踩过坑！Sphinx的指令解析顺序确实会让你用的那种替换标记（|classnumberone|这类）在autoclass之前不生效——毕竟autoclass是被autodoc模块直接解析的，而替换标记通常是在文档渲染的后期才会被处理。这里给你几个实用的解决办法：

方法一：用Jinja2模板变量（最简单直接） #

Sphinx原生支持在.rst文件里使用Jinja2语法，你可以用模板变量来动态指定目标类，完全绕开替换标记的优先级问题。

步骤1：在conf.py里配置变量 #

你可以把目标类作为上下文变量传递给模板，甚至支持通过环境变量动态切换：

import os

# 默认目标类
default_class = "mymodule.classnumberone"
# 从环境变量读取，没有的话用默认值
target_class = os.getenv('SPHINX_TARGET_CLASS', default_class)

# 把变量添加到html上下文，让rst能访问到
html_context = {
    "target_class": target_class
}

步骤2：在rst文件里使用变量 #

直接在autoclass里用Jinja变量即可：

.. autoclass:: {{ target_class }}
   :members:
   :undoc-members:

动态切换的方式 #

构建文档时，通过环境变量指定不同的类：

# 生成classnumberone的文档
make html

# 生成classnumbertwo的文档
SPHINX_TARGET_CLASS=mymodule.classnumbertwo make html

方法二：自定义动态autoclass指令（更灵活） #

如果需要在rst里直接用替换标记（比如|classnumberone|），可以写一个简单的Sphinx扩展，先处理替换再调用autoclass的逻辑。

步骤1：在conf.py里添加扩展代码 #

from sphinx.ext.autodoc import AutoclassDocumenter
from sphinx.util.docutils import SphinxDirective
from docutils.statemachine import ViewList

class DynamicAutoclassDirective(SphinxDirective):
    required_arguments = 1
    option_spec = AutoclassDocumenter.option_spec  # 复用autoclass的选项

    def run(self):
        # 先处理替换标记：把参数里的|xxx|替换成实际的类路径
        raw_class = self.arguments[0]
        # 用Sphinx的替换字典处理标记
        target_class = self.env.get_domain('std').substitute(raw_class, self.lineno)
        
        # 构建autoclass的rst内容
        autoclass_lines = [f'.. autoclass:: {target_class}']
        # 把当前指令的选项（比如:members:）加上
        for opt_name, opt_value in self.options.items():
            if opt_value is None:
                autoclass_lines.append(f'   :{opt_name}:')
            else:
                autoclass_lines.append(f'   :{opt_name}: {opt_value}')
        
        # 解析这段生成的rst
        vl = ViewList(autoclass_lines, self.source)
        self.state.nested_parse(vl, 0, self.content)
        return []

def setup(app):
    # 注册自定义指令
    app.add_directive('dynamic-autoclass', DynamicAutoclassDirective)
    # 注册替换标记（也可以在rst里用.. |xxx| replace:: ...）
    app.add_config_value('substitutions', {}, 'env')
    # 示例替换规则
    app.config.substitutions.update({
        'classnumberone': 'mymodule.classnumberone',
        'classnumbertwo': 'mymodule.classnumbertwo',
        'moduleplusclass': 'mymodule.classnumberthree'
    })

步骤2：在rst里使用自定义指令 #

现在你可以直接用替换标记了：

.. |classnumberone| replace:: mymodule.classnumberone

.. dynamic-autoclass:: |classnumberone|
   :members:

方法三：用autodoc的钩子（进阶场景） #

如果需要更细粒度的控制（比如根据文档上下文自动切换类），可以用autodoc的add_autodocumenter或者autodoc-process-docstring钩子来动态修改要文档化的类。不过这个方案复杂度较高，适合有特殊需求的场景，前面两种方法基本能覆盖大部分情况。

内容的提问来源于stack exchange，提问作者Yerushalmi