如何在Sphinx的make html阶段为所有rst文件添加reST代码片段？

当然可以实现！你想要在make html阶段给每个自动生成的rst文件添加前置或追加的reST代码片段，这里有几个实用的方案，比直接用Jinja模板更贴合你的需求：

方法1：利用Sphinx的source-read事件（最推荐） #

Sphinx提供了很多生命周期事件，其中source-read会在Sphinx读取每个源文件（包括rst和py文件）时触发。你可以在项目的conf.py里注册这个事件，动态修改文件内容，完全不需要改动生成的rst文件本身。

举个例子，假设你想给所有sphinx-apidoc生成的模块/包文档添加前置的扩展配置和追加的提示片段：

def add_custom_snippets(app, docname, source):
    # 过滤只处理sphinx-apidoc生成的文件，比如判断路径包含"modules"或前缀为"_autosummary"
    if "modules" in docname or docname.startswith("_autosummary"):
        # 自定义前置reST片段（比如修改扩展设置、添加说明）
        pre_snippet = """
        .. currentmodule:: your_project_root
        .. default-role:: py:obj
        .. note:: 本文档自动生成，如需修改请调整源码注释或Sphinx配置
        """
        # 自定义追加reST片段
        post_snippet = """
        .. seealso::
           更多API细节请查看对应的Python源码注释
        """
        # source是一个列表，第一个元素就是文件的全部内容，直接修改即可
        source[0] = pre_snippet.strip() + "\n\n" + source[0] + "\n\n" + post_snippet.strip()

def setup(app):
    # 注册source-read事件处理函数
    app.connect('source-read', add_custom_snippets)

这个方法的优势在于：

• 不需要修改sphinx-apidoc的输出文件，也不用调整Makefile
• 可以精准过滤需要修改的文件，避免影响手动编写的rst文档
• 所有逻辑都集中在conf.py里，维护起来更方便

方法2：自定义sphinx-apidoc的生成模板 #

如果你更倾向于在生成rst文件时就直接注入片段，可以修改sphinx-apidoc使用的Jinja模板——其实它的位置并没有你想的那么下游，是在sphinx-apidoc生成rst的阶段生效的：

1. 找到你的Python环境中sphinx-apidoc的模板目录，一般路径是site-packages/sphinx/templates/apidoc，里面有module.rst_t（模块文档模板）和package.rst_t（包文档模板）
2. 把这两个模板文件复制到你的项目根目录下的_templates/apidoc文件夹（如果没有就新建）
3. 打开复制后的模板文件，在开头或结尾添加你需要的reST代码。比如在module.rst_t的最顶部加上：

   .. custom-directive:: 这里是自动添加的前置片段，用于配置扩展
   

4. 运行sphinx-apidoc时，它会自动优先使用你自定义的模板（如果没生效，可以加上--template-dir _templates/apidoc参数）

方法3：通过Makefile预处理rst文件 #

如果想在make html执行前批量修改所有rst文件，可以调整项目的Makefile，添加一个预处理步骤：

# 原有的html目标修改为依赖preprocess_rst
html: preprocess_rst
	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
	@echo
	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

# 新增预处理步骤，给指定rst文件添加片段
preprocess_rst:
	# 遍历source目录下所有sphinx-apidoc生成的rst文件（比如以modules开头的）
	for file in $(SOURCEDIR)/modules*.rst; do \
		# 写入前置片段到临时文件
		echo -e ".. pre-snippet:: 自定义前置内容\n" > temp.rst; \
		# 追加原文件内容
		cat $$file >> temp.rst; \
		# 追加后置片段
		echo -e "\n.. post-snippet:: 自定义后置内容" >> temp.rst; \
		# 替换原文件
		mv temp.rst $$file; \
	done

这个方法适合需要批量修改文件的场景，但要注意做好文件备份，避免意外覆盖手动编写的内容。

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