如何从 readthedocs 站点提供静态非图像资产？答案

【问题标题】：How to serve static non-image asset from a readthedocs site?如何从 readthedocs 站点提供静态非图像资产？
【发布时间】：2013-09-08 10:13:36
【问题描述】：

我的docs 文件夹中有一个assets 文件夹，其中包含与我的项目文档相关的图像和示例输入文件。

图像正确嵌入到我的文档中，但任何指向示例输入文件（作为我的项目二进制文件输入的静态文件）的链接都是 404ed。

例如，这里可能是我的文档中的 reSt 格式文本：

Open this `example`_ input file to see the following result:

.. image:: ../../assets/foo.png

.. _example: ../../assets/bar.tgz

图像foo.png 被正确渲染。从 _example 链接到 tarball 的链接指向 404 页面。

foo.png 和 bar.tgz 两个文件都在主 github 发行版中，并且位于指定的路径中。

我尝试过make html，通过git 推送更改并重建文档。

我该如何解决这个问题，以便文档与 github 发行版中的资产一起使用？（我猜我应该避免链接到原始 github 地址，因为版本控制。）

【问题讨论】：

【解决方案1】：

Read the Docs 不会从您的存储库中提供任意文件；它只服务于 Sphinx 构建过程的结果。因此，不要像示例中那样链接到文件，而是使用 :download: 角色。该角色告诉 Sphinx 将额外文件包含在构建输出的目录中。

因此，修改为使用 :download: 的示例可能如下所示：

Open this :download:`example <../path/to/bar.tgz>` input file to see the following result:

请注意，文件路径是相对于角色出现的 reStructuredText 文件，而不是 HTML 输出。

【讨论】：

@ddbeck 在使用 MarkDown 而不是 ReStructuredText 时有类似的方法吗？
@Alasdair 你是指recommonmark 库吗？我自己还没有真正尝试过，但据我了解，它不支持 Sphinx 的许多功能。要解决此问题，您可以使用 conf.py 文件中的 Sphinx html_extra_path 设置将任意文件添加到 HTML 输出中。
谢谢会试一试。目前正在与用于生产的自托管 readthedocs 搏斗（开发环境工作正常）。会回到这个。