在(Python) Sphinx文档中按原样包含文本文件

Question

(使用Python-Sphinx文档工具)

我有一个 .txt 日志文件，想把它直接放到 _build/html 里，不想改动它。那我需要在 conf.py、index.rst 等文件里做什么修改呢？

这是我的文件结构：

src/
    index.rst
    some_doc.rst
    somefile.txt

我该怎么把 somefile.txt 加入到html构建里呢？我试着在 index.rst 里加了一行：

Contents:

.. toctree::
   :maxdepth: 2

   some_doc
   "somefile.txt"

希望这样能神奇地工作，但这里没有魔法发生！

假设这真的有可能，我该在 some_doc.rst 里写什么来引用/链接那个文件呢？

注意 是的，我知道我可以把它放在 /static 里就算了，但那样感觉太像是个临时解决方案，而且也不好看。

Answer 1

你可以在sphinx中使用以下内容

.. literalinclude:: file.txt
   :text:

这样做会把文件的内容显示出来，就像放在代码块里一样。

Answer 2

我觉得你可以包含一个外部文档片段，具体的说明可以在这里找到：

http://docutils.sourceforge.net/docs/ref/rst/directives.html#including-an-external-document-fragment

根据那段文字，像下面这样应该可以实现：

.. include:: inclusion.txt
   :literal:

Answer 3

正确的答案是 :download: 角色。

参考：Georg 在 Sphinx 邮件列表上的回答