git - 如何从 readthedocs 站点提供静态非图像 Assets ？

Question

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

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

例如，这里可能是我文档中重新格式化的文本:

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 发行版中，并且位于指定的路径中。

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

我该如何着手解决这个问题，以便文档与作为 github 发行版一部分的 Assets 一起使用？ (我猜我应该避免链接到原始 github 地址，因为版本控制。)

Answer 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 输出。