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!

blog comments powered by Disqus
 
vanrees.org 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):