Sphinx 4.0.2环境下获取reStructuredText源文件名配置失效问题

根因说明 #

Sphinx原生的rst_epilog配置本身不支持Jinja语法解析，之前你这套配置能在nbsphinx场景下生效，是因为nbsphinx扩展额外做了Jinja渲染的适配逻辑，直接在原生Sphinx 4.0.2环境运行时没有对应渲染逻辑，所以Jinja语法会被当做普通rst文本处理，无法生成预期内容。

修复方案 #

方案1：自定义扩展实现（不依赖nbsphinx） #

通过绑定Sphinx的source-read事件，在rst内容解析前做Jinja渲染，步骤如下：

1. 在你的Sphinx项目扩展目录（通常为_ext）下新建jinja_rst_support.py，内容如下：

from jinja2 import Template

def render_rst_with_jinja(app, docname, source):
    # 传入Sphinx环境变量作为Jinja上下文
    rendered = Template(source[0]).render(
        env=app.env,
        docname=docname
    )
    # 必须修改source列表的第一个元素才会生效
    source[0] = rendered

def setup(app):
    app.connect("source-read", render_rst_with_jinja)
    return {
        "version": "0.1",
        "parallel_read_safe": True
    }

2. 修改conf.py配置：

import sys
import os
# 扩展目录加入Python导入路径
sys.path.append(os.path.abspath("./_ext"))
# 加载扩展，注意保留你原有其他扩展配置
extensions = [
    # 你的其他原有扩展
    "jinja_rst_support",
]
# 保留你原来的rst_epilog配置即可
rst_epilog = r"""
{% set docname = env.doc2path(env.docname, base=None) %}

.. tip:: this is {{ docname }}
"""

方案2：兼容nbsphinx场景 #

如果你本身就在用nbsphinx扩展，只要升级nbsphinx到0.8.7及以上版本即可兼容Sphinx 4.0.2，不需要额外写自定义扩展，原有配置可以直接生效。

之前自定义扩展不生效的常见原因 #

• 没有绑定正确的source-read事件，或者回调函数没有修改传入的source[0]参数
• Jinja渲染时没有传入env等模板需要的上下文变量，导致变量解析失败
• 扩展的setup函数没有返回parallel_read_safe标识，并行构建场景下会被Sphinx禁用

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