如何在Sphinx中结合:target:与:download:实现图片跳转至视频

问题背景 #

项目目录结构：

_build
index.rst
foo.rst
foo/myimage.jpeg
foo/myvideo.webm

需求：

1. 在foo.rst中显示foo/myimage.jpeg，点击图片可跳转至foo/myvideo.webm
2. 无法将图片和视频放入_static目录，需通过Sphinx自动将这两个文件复制到_build目录
3. 之前尝试的替换指令写法无效，图片跳转目标变成了:download:foo/myvideo.webm``字符串

解决方案 #

步骤1：确保Sphinx自动复制资源到_build #

在foo.rst中添加隐藏的:download:指令，触发Sphinx将图片和视频复制到_build/_downloads目录（:hidden:参数避免在文档中显示下载链接）：

.. only:: html
   .. _video_target:
   .. download:: foo/myvideo.webm
      :hidden:

   .. download:: foo/myimage.jpeg
      :hidden:

步骤2：实现图片点击跳转视频 #

使用:download:引用图片（确保图片被正确复制），并通过:target:指向视频的引用标签video_target：

.. image:: :download:`foo/myimage.jpeg`
   :target: video_target
   :alt: My target image

原理说明 #

• :download:指令会自动将指定文件复制到_build/_downloads目录，满足资源复制需求
• 给视频的:download:添加_video_target引用标签，图片的:target:直接指向该标签，即可实现点击图片跳转视频的效果
• :hidden:参数确保下载链接不会显示在最终文档中，只用于触发资源复制

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