[FM Discuss] Python document generation tool; might be worthwhile studying for comparison

[Andy Oram]

I heard about this from a colleague and thought we might learn from what they do and why; just passing on the summary he gave me.

---

http://sphinx.pocoo.org/

Latest features I've found useful:
- Cross-site referencing (makes it a snap to refer to docs on a  
related project in another location)
- Diagramming extension
- Automatic PDF generation

The extensions are incredibly useful:
http://sphinx.pocoo.org/extensions.html

I usually generate JSON docs, upload them to my own server at pylonshq.com 
, then allow comments in the template generated. Later I integrate and  
update the docs based on the comments, and re-upload a new batch.  
Works rather well, and enforces a consistency in the docs that's  
rather pleasing.