Include a text file *as is* in (Python) Sphinx Docs

Question

(using Python-Sphinx Documentation tool)

I have a .txt log file I'd like to build into _build/html unaltered. What do I need to alter in conf.py, index.rst, etc.

Here is the layout:

src/
    index.rst
    some_doc.rst
    somefile.txt

How do I get somefile.txt into the html build? I tried adding a line like this to index.rst:

Contents:

.. toctree::
   :maxdepth: 2

   some_doc
   "somefile.txt"

hoping it would work by magic, but no magic here!

Assuming this is even possible, what would I put in some_doc.rst to refer/link to that file?

Note Yes, I'm aware I could put it in /static and just be done with it, but that seems like a total hack, and ugly.

Answer 1

I think you can include an external document fragment, as described here:

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

From that text, something like this should do it:

.. include:: inclusion.txt
   :literal:

Answer 2

The correct answer is the :download: role.

Cf: Georg's answer on the Sphinx Mailing List