Take the 2-minute tour ×

I'm writing a Django app to serve some documentation written in RestructuredText. I have many documents written in *.rst, each of them is quite long with many section, subsection and so on.

Display the whole document in a single page is not a problem using Django filters, but I'd rather have just the topic index on a first page, whit links to an URL where I can display a single section / subsection (which will need some 'previous | up | home | next' link I guess...). In a way similar to a 'multiple HTML page output' as in a docbook / XML to HTML conversion.

Can anyone point me to some direction to build a document tree of a *.rst document an parse a single section of it, or suggest a clever way to obtain a similar result?

share|improve this question
add comment

1 Answer

up vote 1 down vote accepted

Choice 1. Include URL links to the other parts of the document.

You write an index.rst, part1.rst, part2.rst, etc. And your index.rst has links to the other parts. This requires almost no work, except careful planning to make sure that your RST HTML links are correct.

There's no "parse". You just break your document into sections. Manually.

[This seems so obvious, I'm afraid to mention it.]

Choice 2. Use Sphinx. It manages table-of-contents and inter-document connections very nicely.

However, the Sphinx extensions to RST aren't handled directly by Django, so you'd need to save the Sphinx output and then display that in Django. We use the JSON HTML Builder (http://sphinx.pocoo.org/builders.html?highlight=json#sphinx.builders.html.JSONHTMLBuilder) output from Sphinx. Then we render these documents through a template.

share|improve this answer
Thanks, I've been considering Choice 1 which seems the way other documentation has been sub-divided in other projects (usually using Sphinx, which I've been using as well). Choice 2. looks interesting, but I would like (I'm looking for a way to): - keep my docs in *.rst, so I can manage them with Git and generate output as needed - Keep all of the process in Django without the need of passing through Sphinx Choice 1. looks simple and easy to implement: I'll look at my library and see how my documents adapt to it. Thanks for your advice. –  eaman Aug 24 '10 at 16:46
add comment

Your Answer


