Multiple pages html output from a .rst document in Django

Question

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?

Answer 1

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.