在Python Sphinx中，如何链接到_static目录中的文件？

Question

我有一些代码和数据样本，我将它们复制到 _static 目录中，并希望在文档中链接到这些文件，类似于：

.. _pca-run.py: _static/example.data

但问题在于sphinx没有创建一个正确的相对链接到这个文件，而只是直接复制了值。因此，在嵌套文件中，_static不在同一目录下的链接无法正常工作。

- Mitar

---

似乎有一个“:download:”角色：https://dev59.com/UnE85IYBdhLWcg3wJQCt - Mitar

Answer 1

您需要的是:download: 文本角色（正如Mitar在他的评论中提到的）。

使用它将告诉Sphinx将给定文件复制到"_downloads"目录并创建一个超链接到它。 这最初是用于可下载文件，例如PDF（在html输出中）或tarball等。 但是对于任何其他非ReST文件也可以正常工作。

如果您真的想要，您可以编写一个扩展来完成此操作，但我从未见过这样的需求，因为:download: 正好符合我的需求。 https://www.sphinx-doc.org/en/stable/usage/restructuredtext/roles.html#role-download

- Kevin Horn

---

但是“：download：”非常冗长。如果您想多次使用它，那就很烦人。 - Mitar

你是否知道有没有类似于:download:但可以接受通配符（或glob模式）的角色？ - unode

@Unode：我不确定你为什么想要这样做，但你可能需要创建自己的扩展。不过，这并不难。请参阅sphinx-contrib，其中有很多示例。 - Kevin Horn

@KevinHorn 我想自动获取某个文件夹中符合特定模式的所有文件的下载链接列表，比如：*.doc。 - unode

@Unode：我认为你需要编写自己的扩展程序来实现这个。 - Kevin Horn

Answer 2

对于图片，只需找到正确的答案：在目标文件的路径前添加/。对于从automodule引用的图像

.. image:: some_file.png

将相对于当前正在处理的Python文件引用文件some_file.png，而

.. image:: /some_file.png

将引用文件some_file.png相对于conf.py的位置。这样，就无需在源层次结构中添加图像。

- Raffi

---

如果你将source和build目录分开，你需要做同样的事情。这意味着Sphinx不会查找conf.py的相对位置，而是查找conf.py内部的html_static_path变量。 - Eray Erdin