convert trac faq section into documentation sections

[Mike Bayer]

let's imitate django's file layout:

/faq/
/faq/general/
/faq/setup/
/faq/setup/#how-to-configure-logging
/faq/setup/...
/faq/metadata/
.. etc.

also lots of content in the FAQ is out of date, poorly written, needs updating. new FAQ sections are needed as well:

• how do i use caching with SQLAlchemy ?
• when do i close my session ?
• should I use declarative ?
• how do create new SQL constructs ?
• how do i run some code every time an object is inserted? updated? deleted?
• how do i do versioning ?
• how do i make a self-referential many-to-many ? (so many people ask this one for some reason...)
• how can I make my SQLalchemy application faster ? (there's lots for this...)

[Mike Bayer]

• why are the SQLAlchemy core and ORM considered "separate", but are in one distribution ? (answer - the core is enhanced and fixed in very fine synchronization with the ORM. Our release cycle is best suited by these two packages bundled together. )

[Mike Bayer]

Another feature I've wanted for a long time - to add a code to all SQLAlchemy exception messsages, then add to the FAQ a large section on "Error Messages" - describe every one including what causes it, lookup by code.

[Former user]

(original author: ejo) Replying to zzzeek:

+1 on that! The messages as they stand are already pretty good, but currently I think users mostly just paste exception text into Google and hope for useful discussion threads to come up. Official long-form explanations would be a great resource.

[Mike Bayer]

09b93477d26e8298c255b98eb0d6371839bbfa87 0.8

4268ea06b3efe116361157fa2ad15 master