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:


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! logo

About me

My name is Reinout van Rees and I work a lot with Python (programming language) and Django (website framework). I live in The Netherlands and I'm happily married to Annie van Rees-Kooiman.

Weblog feeds

Most of my website content is in my weblog. You can keep up to date by subscribing to the automatic feeds (for instance with Google reader):