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?
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