[Sqlalchemy-tickets] Issue #3138: Streamlined API docs? (zzzeek/sqlalchemy)

[jvanasco <iss...@bi...>]

New issue 3138: Streamlined API docs?
https://bitbucket.org/zzzeek/sqlalchemy/issue/3138/streamlined-api-docs

jvanasco:

First off -- I'm not sure if this is possible.  I looked into the SqlA docs, and couldn't figure out a way to do this with RST.  If there is a way and consensus, I would be glad to do the busywork on this idea....

The docs are getting hard for me to read and reference.  They're absolutely great in content --  it's just the interface.  

The two big issues I've encountered are:

a- Many classes in the docs require paginating across dozens of screens to see all the available methods.  `Object` and `Session` are good examples.  I think they'd benefit greatly by an "Section Table-Of-Contents".  RST doesn't seem to support that though.

a- The narrative docs are amazing, possibly the best in Python.  But there is no "API Reference" style documentation online, where one can quickly navigate into a specific module or method.  I think it might be worth adding to the docs generation (online and local) some automatic API output , along the lines of what Twisted does with pydoctor or Pyramid does with Sphinx.