it would be handy for each app to have a summary of url names and template names so it's easy to see how to link to a view and what templates can be override
Maybe there is a way to automate introspection so that it is not only accurate but remains so?
I imagine this feature looking something like django.contrib.admindocs (/admin/doc/views/) except formatted properly in a sphinx format
This could get things started:
http://gist.github.com/418395
For example:
$ python find_urls.py > docs/urls.txt
However, I think that it is probably best to not have docs generated past an initial helper script to seed things.
Generated documentation doesn't offer much more benefit that just reading the code through a code browser like on Github, for instance.
I think the big question here is more how to organize it. Should there be app centric documentation that has sections for it's templates, urls, etc. Or should it be organized by function/type where there would be a master index of urls, templates, etc. across all applications.
I could see both being beneficial so it might be worth having both and having them cross indexed/linked.
Thoughts?
I have started work on this in:
http://github.com/paltman/pinax/tree/doc-apps/
I'll push upstream after I finish up each app.
