Including external files in Sphinx¶

Tags: python

I’m writing my documentation with sphinx.

In my project, I’ve got a doc/ subdirectory with the index.txt and the rest of the documentation, so the total structure looks something like this:

myproject/
myproject/README.txt
myproject/setup.py
myproject/doc/
myproject/doc/index.txt
myproject/doc/conf.py
myproject/myproject/__init__.py
myproject/myproject/actual_code.py
myproject/myproject/some_doctest.txt

What I wanted to, of course was to include the README.txt, CHANGES.txt and so on. And also the some_doctest.txt. But they’re all outside my documentation directory, which is the directory where sphinx looks for .txt files.

What are the options I tried?

• Just putting ../README in a toctree statement didn’t

seem to work.

• Copy-pasting the files is a no-go.
• Symlinks don’t work in svn.
• Adjusting the makefile is possible, but that was getting automatically generated for me by collective.recipe.sphinxbuilder, a buildout recipe, so I didn’t really want to touch that.

I asked around on the sphinx-dev mailinglist and got the correct answer: just use restructuredtext’s normal include directive. Thanks!

I totally forgot to look at restructuredtext itself and only looked at sphinx :-)

So now I have, for instance, a project.txt that looks like:

.. include:: ../README.txt

.. include:: ../TODO.txt

.. include:: ../CHANGES.txt

.. include:: ../CREDITS.txt

Works fine!