Clarify what autogenerate compares

### Description
<!-- Describe your changes in detail -->
I was struggling with empty upgrade/downgrade functions because both my database and my ORM were up to date. I wrongly assumed the comparison was against the previous database scheme as per the prior revision script(s).

### Checklist
<!-- go over following points. check them with an `x` if they do apply, (they turn into clickable checkboxes once the PR is submitted, so no need to do everything at once)

-->

This pull request is:

- [x] A documentation / typographical error fix
	- Good to go, no issue or tests are needed
- [ ] A short code fix
	- please include the issue number, and create an issue if none exists, which
	  must include a complete example of the issue.  one line code fixes without an
	  issue and demonstration will not be accepted.
	- Please include: `Fixes: #<issue number>` in the commit message
	- please include tests.   one line code fixes without tests will not be accepted.
- [ ] A new feature implementation
	- please include the issue number, and create an issue if none exists, which must
	  include a complete example of how the feature would look.
	- Please include: `Fixes: #<issue number>` in the commit message
	- please include tests.

**Have a nice day!**

Closes: #1570
Pull-request: https://github.com/sqlalchemy/alembic/pull/1570
Pull-request-sha: dec968b136a813d27e1d2bca04574a2399343a1a

Change-Id: I04dadc3c3d26ad000aca499208d8024cd63eec40

diff --git a/docs/build/autogenerate.rst b/docs/build/autogenerate.rst
index 519aa5bc4f3e159cb658e2e1d5a4d61d49c66a94..c7641fe4f06b5a2e9e406ce727fc7a96fa4f075c 100644 (file)
--- a/docs/build/autogenerate.rst
+++ b/docs/build/autogenerate.rst
@@ -1,10 +1,12 @@
 Auto Generating Migrations
 ===========================
 
-Alembic can view the status of the database and compare against the table metadata
-in the application, generating the "obvious" migrations based on a comparison.  This
-is achieved using the ``--autogenerate`` option to the ``alembic revision`` command,
-which places so-called *candidate* migrations into our new migrations file.  We
+Alembic can view the status of the database (pointed to by ``sqlalchemy.url`` in
+your ``alemic.ini`` file using the *current* schema) and compare against the
+table metadata in the application (your ORM which defines the *proposed* schema),
+generating the "obvious" migrations based on a comparison.  This is achieved
+using the ``--autogenerate`` option to the ``alembic revision`` command, which
+places so-called *candidate* migrations into our new migrations file.  We
 review and modify these by hand as needed, then proceed normally.
 
 To use autogenerate, we first need to modify our ``env.py`` so that it gets access