Clarify what autogenerate compares

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).

diff --git a/docs/build/autogenerate.rst b/docs/build/autogenerate.rst
index 519aa5bc4f3e159cb658e2e1d5a4d61d49c66a94..835d407356539069e89578a7f5c653035b830c09 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 *previous* schema) and compare against the
+table metadata in the application (your ORM which defines the *latest* 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