- docs

- note about unicode
- dont need importlater
- use correct type_ kw arg
- log cols/tables/etc as we autogenerate

2 files changed, 69 insertions, 27 deletions

diff --git a/docs/build/front.rst b/docs/build/front.rst
index 25248d5..46955a3 100644
--- a/docs/build/front.rst
+++ b/docs/build/front.rst
@@ -7,12 +7,24 @@ Information about the Alembic project.
 Project Homepage
 ================
 
-Alembic is hosted on `Bitbucket <http://bitbucket.org>`_ - the lead project page is at https://bitbucket.org/zzzeek/alembic.  Source
-code is tracked here using `Mercurial <http://mercurial.selenic.com/>`_.
+Alembic is hosted on `Bitbucket <http://bitbucket.org>`_ - the lead project
+page is at https://bitbucket.org/zzzeek/alembic. Source code is tracked here
+using `Mercurial <http://mercurial.selenic.com/>`_.
 
-Releases and project status are available on Pypi at http://pypi.python.org/pypi/alembic.
+Releases and project status are available on Pypi at
+http://pypi.python.org/pypi/alembic.
 
-The most recent published version of this documentation should be at http://packages.python.org/alembic/.
+The most recent published version of this documentation should be at
+http://packages.python.org/alembic/.
+
+Project Status
+==============
+
+Note that Alembic is still in alpha status.   Users should take
+care to report bugs and missing features (see :ref:`bugs`) on an as-needed
+basis.  It should be expected that the development version may be required
+for proper implementation of recently repaired issues in between releases;
+the latest tip is always available at https://bitbucket.org/zzzeek/alembic/get/tip.tar.gz.
 
 .. _installation:
 
@@ -40,6 +52,8 @@ projects.
 User issues, discussion of potential bugs and features should be posted
 to the Alembic Google Group at `sqlalchemy-alembic <https://groups.google.com/group/sqlalchemy-alembic>`_.
 
+.. _bugs:
+
 Bugs
 ====
 Bugs and feature enhancements to Alembic should be reported on the `Bitbucket
diff --git a/docs/build/tutorial.rst b/docs/build/tutorial.rst
index 470adb4..c621769 100644
--- a/docs/build/tutorial.rst
+++ b/docs/build/tutorial.rst
@@ -204,6 +204,7 @@ A new file ``1975ea83b712.py`` is generated.  Looking inside the file::
     down_revision = None
 
     from alembic.op import *
+    import sqlalchemy as sa
 
     def upgrade():
         pass
@@ -305,6 +306,7 @@ Let's edit this file and add a new column to the ``account`` table::
     down_revision = '1975ea83b712'
 
     from alembic.op import *
+    import sqlalchemy as sa
     from sqlalchemy import DateTime, Column
 
     def upgrade():
@@ -364,34 +366,56 @@ Back to nothing - and up again::
 Auto Generating Migrations
 ===========================
 
-.. note:: this functionality is not yet implemented.  Specific details here
-   are subject to change.
-
 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`` command.
+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
 to a table metadata object that contains the target.  Suppose our application
 has a `declarative base <http://www.sqlalchemy.org/docs/orm/extensions/declarative.html#synopsis>`_
 in ``myapp.mymodel``.  This base contains a :class:`~sqlalchemy.schema.MetaData` object which
 contains :class:`~sqlalchemy.schema.Table` objects defining our database.  We make sure this
-is loaded in ``env.py`` and then passed to :func:`.context.configure_connection` via
-``use_metadata``::
+is loaded in ``env.py`` and then passed to :func:`.context.configure` via the
+``autogenerate_metadata`` argument.   The ``env.py`` sample script already has a 
+variable declaration near the top for our convenience, where we replace ``None``
+with our :class:`~sqlalchemy.schema.MetaData`.  Starting with::
 
-    from myapp.mymodel import Base
+    # add your model's MetaData object here
+    # for 'autogenerate' support
+    # from myapp import mymodel
+    # autogenerate_metadata = mymodel.Base.metadata
+    autogenerate_metadata = None
 
-    connection = engine.connect()
-    context.configure_connection(connection, use_metadata=Base.metadata)
-    trans = connection.begin()
-    try:
-        context.run_migrations()
-        trans.commit()
-    except:
-        trans.rollback()
-        raise
+we change to::
 
-We then create an upgrade file in the usual way adding ``--autogenerate``.  Suppose
+    from myapp.mymodel import Base
+    autogenerate_metadata = Base.metadata
+
+If we look later in the script, down in ``run_migrations_online()``, 
+we can see the directive passed to :func:`.context.configure`::
+
+    def run_migrations_online():
+        engine = engine_from_config(
+                    config.get_section(config.config_ini_section), prefix='sqlalchemy.')
+
+        connection = engine.connect()
+        context.configure(
+                    connection=connection, 
+                    autogenerate_metadata=autogenerate_metadata
+                    )
+
+        trans = connection.begin()
+        try:
+            context.run_migrations()
+            trans.commit()
+        except:
+            trans.rollback()
+            raise
+
+We can then use the ``alembic revision`` command in conjunction with the 
+``--autogenerate`` option.  Suppose
 our :class:`~sqlalchemy.schema.MetaData` contained a definition for the ``account`` table,
 and the database did not.  We'd get output like::
 
@@ -414,20 +438,24 @@ is already present::
     down_revision = None
 
     from alembic.op import *
-
     import sqlalchemy as sa
 
     def upgrade():
+        ### commands auto generated by Alembic - please adjust! ###
         create_table(
-            'account',
-            sa.Column('id', sa.INTEGER, primary_key=True),
-            sa.Column('name', sa.VARCHAR(50), nullable=False),
-            sa.Column('description', sa.VARCHAR(200)),
-            sa.Column('last_transaction_date', sa.DATETIME)
+        'account',
+        sa.Column('id', sa.Integer()),
+        sa.Column('name', sa.String(length=50), nullable=False),
+        sa.Column('description', sa.VARCHAR(200)),
+        sa.Column('last_transaction_date', sa.DateTime()),
+        sa.PrimaryKeyConstraint('id')
+        ### end Alembic commands ###
         )
 
     def downgrade():
+        ### commands auto generated by Alembic - please adjust! ###
         drop_table("account")
+        ### end Alembic commands ###
 
 The migration hasn't actually run yet, of course.  We do that via the usual ``upgrade``
 command.   We should also go into our migration file and alter it as needed, including