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.

score 31 · Answer 1 · answered May 27 '10 at 14:27

31

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

From that text, something like this should do it:

.. include:: inclusion.txt
   :literal:

answered May 27 '10 at 14:27

djc

1

not quite what I want, but I'm looking over :raw: and other roles. I'm not trying to include a "fragment", but bring over a while file *as is*, so I can link to it, a la -> if you look at the `log `_ .... – Gregg Lind May 27 '10 at 15:17
1

this does answer the question's title, which hints at a different question altogether ;-) – odony Mar 04 '16 at 18:52

score 10 · Accepted Answer · edited Apr 10 '19 at 19:15

10

The correct answer is the :download: role.

edited Apr 10 '19 at 19:15

jmq

answered May 28 '10 at 20:12

Gregg Lind

5

How is adding a download link the answer to "how to build in a file unaltered?" – mabraham Jan 13 '15 at 17:38
1

The mailing list link in the answer is dead. Is this the message that you refer to? https://groups.google.com/d/msg/sphinx-users/LZzb8wlAoSs/FHU1eN6RMBAJ – mzjn Jul 23 '15 at 10:51

youngtrashbag · Answer 3 · 2021-12-04T13:57:41.607

-1

You can use the following in sphinx

.. literalinclude:: file.txt
   :text:

It will show the content of the file, as if it were in a code block.

edited Dec 04 '21 at 13:57

answered Dec 03 '21 at 10:55

youngtrashbag

As it’s currently written, your answer is unclear. Please [edit] to add additional details that will help others understand how this addresses the question asked. You can find more information on how to write good answers [in the help center](/help/how-to-answer). – Community Dec 03 '21 at 11:40

3 Answers3