Sphinx RST文档中获取_static目录下资源正确相对路径的方法

你使用的{{ pathto() }}是Sphinx HTML模板专属的Jinja语法，默认RST文件不会经过Jinja引擎解析，因此相关标签会被当做普通文本直接输出，无法生成正确的相对路径。

方案1：无扩展，全局开启RST的Jinja渲染 #

不需要安装额外依赖，只需修改项目的conf.py配置即可：

1. 在conf.py末尾添加如下代码：

def rstjinja(app, docname, source):
    # 将RST内容作为Jinja模板渲染，解析{{ }}语法
    rendered = app.builder.templates.render_string(
        source[0], app.config.html_context
    )
    source[0] = rendered

def setup(app):
    # 绑定RST文件读取后的回调事件
    app.connect("source-read", rstjinja)

2. 保存配置后重新执行make html，你原来写的{{ pathto('_static/_resources/intro-01_v3.mp4') }}就会被自动替换为对应层级的相对路径，视频可以正常播放。

方案2：使用专用视频扩展（更省心） #

如果不想手动写raw HTML和处理路径，可以用Sphinx官方维护的视频扩展：

1. 安装扩展：

pip install sphinxcontrib-video

2. 在conf.py的extensions列表中添加该扩展：

extensions = [
    # 你原来的其他扩展
    'sphinxcontrib.video',
]

3. 把原来的raw HTML块替换为如下RST指令即可，路径会自动生成：

.. video:: _static/_resources/intro-01_v3.mp4
   :width: 100%
   :height: 540
   :controls:

请确认你的视频文件已经存放在source/_static/_resources/目录下，且conf.py中的html_static_path配置为默认的['_static']，这是路径正常生成的前提。

内容的提问来源于stack exchange，提问作者M.A. Heshmat Khah