问题:如何从 readthedocs 站点提供静态非图像资产?

我的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 地址,因为版本控制。)

解答

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

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

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

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