Parsing restructured text in django (and python)

Question

I'm going to manage some documentation using Django (I come from Sphinx) in order to have more control on the output. The docs are in rst (restructured text) in a git archive, and it's trivial to display them in HTML using a filter. My problem is that they are quite long, and I'd like to have more control on how the pagination goes, so I can show a single section per HTML page, have comments for a single section and so on...

My goal would be to be able to parse each doc, create my TOC with links to each section in a separate HMTL page, where a view would go through whole doc to render in html just a section.

I understand that it's mostly a issue of docutils, the most interesting example I've been able to find is: http://www.ibm.com/developerworks/library/x-matters24/#code2 but it seems outdated and the examples in section "Tree-oriented processing", which is where the magic goes, don't seem work with my version of docutils. Article is good: I could use more of the same subject!

Is there something similar to what I'm planning to do already available that I can study, or maybe could someone point me to a gentle introduction to docutils for parsing rst documents?

Answer 1

Here is a blog describing howto make a custom rst writer and call it from Django. I think it should give you a good start http://www.arnebrodowski.de/blog/write-your-own-restructuredtext-writer.html

Answer 2

Pygments has a ReST lexer that you could examine (or possibly even use directly).