如何在Sphinx的conf.py中为指定指令设置默认选项，避免重复填写参数

完全可以在conf.py中为autosummary指令设置固定的:toctree:默认值，不需要每次手动编写参数，具体操作如下：

操作步骤 #

1. 首先确认conf.py的extensions列表中已经引入了autosummary扩展：

extensions = [
    # 其余扩展
    'sphinx.ext.autosummary',
]

2. 在conf.py的末尾添加以下代码，直接修改autosummary指令的默认选项：

from sphinx.ext.autosummary import Autosummary

# 配置toctree选项的默认值为r
Autosummary.option_spec['toctree'] = lambda val: val
Autosummary.default_options['toctree'] = 'r'

效果说明 #

• 配置完成后，所有未手动指定:toctree:选项的autosummary指令，都会自动应用toctree: r的配置，完全避免遗漏参数的问题
• 如果你在某个autosummary块中手动指定了其他:toctree:路径，手动配置的优先级更高，会自动覆盖默认值，不影响特殊场景的自定义需求
• 该配置兼容Sphinx 4.x及以上的所有主流版本

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