如何从readthedocs网站提供静态非图像资产？

Question

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

图像在我的文档中正确嵌入，但是样本输入文件的任何链接（作为项目二进制文件输入的静态文件）都是404。

例如，这里可能是我的文档中的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地址，因为版本控制。）

Answer 1

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

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

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

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