在 Python sphinx 中，如何链接到 _static 目录中的文件答案

【问题标题】：In Python sphinx, how to link to a file in _static directory在 Python sphinx 中，如何链接到 _static 目录中的文件
【发布时间】：2011-12-12 14:30:42
【问题描述】：

我有一些代码和数据示例复制到_static 目录，我想链接到文档中的这些文件，例如：

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

但问题是 sphinx 没有创建到该文件的正确相对链接，而只是按原样复制值。因此对于_static 不在同一目录中的嵌套文件，链接不起作用。

【问题讨论】：

好像有:download:角色：stackoverflow.com/questions/2921724/…

标签： python-sphinx

【解决方案1】：

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

https://www.sphinx-doc.org/en/stable/usage/restructuredtext/roles.html#role-download

使用这将告诉 Sphinx 将给定文件复制到“_downloads”目录并创建一个超链接。这最初旨在用于可下载文件，例如 PDF（在 html 输出中）或 tarball 或其他文件。不过，它适用于任何其他非 ReST 文件。

如果你真的想要，你可以写一个扩展来做这件事，但我从来没有看到有必要这样做，因为:download: 正是我想要的。

【讨论】：

但是:download: 非常冗长。如果你想多次使用它，它会变得很累。
您是否知道有任何角色类似于:download: 但接受通配符（或glob 模式）？
@Unode：我不确定我理解您为什么要这样做，但您可能必须创建自己的扩展程序。不过这并不难。请参阅sphinx-contrib 获取大量示例。
@KevinHorn 我想自动列出某个文件夹中所有文件的下载链接并匹配某种模式，比如：*.doc
@Unode：我认为你需要为此编写自己的扩展。

【解决方案2】：

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

.. image:: some_file.png

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

.. image:: /some_file.png

将引用文件some_file.png 相对于conf.py 的位置。这样，就不需要用图像污染源层次结构。

【讨论】：

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