Make API docs easier to navigate

[bitprophet]

Description

• Autodoc detail pages are not always alphabetical, which sucks.
  • Order of full docstring sections is not alphabetical on at least some pages (e.g. the page for, say, 'decorators' might not have 'hosts' then 'roles'. Off the cuff example.)
  • May be due to such files having explicit signature definitions due to Use 3rd party "decorator" module to fix introspection for decorated functions #103?
• Also on autodoc detail pages: see if there's a way to list autodoc'd functions in a sidebar or top-of-page nav menu. It's very annoying to have to scroll through the page looking for the function in question!
  • E.g. docs.python.org does this for the built-in functions page -- see if that's an OOB Sphinx feature or something we can crib.
• See if there is a way for an "enhanced" toctree on the docs index page for the API/contrib sections. Need to indicate what is in those sections -- titles are not sufficient.

---

Originally submitted by Jeff Forcier (bitprophet) on 2009-11-11 at 11:50pm EST