- fix up docs and add changelogs for #301 and #302ticket_302

15 files changed, 85 insertions, 38 deletions

diff --git a/alembic/config.py b/alembic/config.py
index 74b4d17..b3fc36f 100644
--- a/alembic/config.py
+++ b/alembic/config.py
@@ -130,7 +130,7 @@ class Config(object):
         This is a utility dictionary which can include not just strings but
         engines, connections, schema objects, or anything else.
         Use this to pass objects into an env.py script, such as passing
-        a :class:`.Connection` when calling
+        a :class:`sqlalchemy.engine.base.Connection` when calling
         commands from :mod:`alembic.command` programmatically.
 
         .. versionadded:: 0.7.5
@@ -155,7 +155,7 @@ class Config(object):
 
     @util.memoized_property
     def file_config(self):
-        """Return the underlying :class:`ConfigParser` object.
+        """Return the underlying ``ConfigParser`` object.
 
         Direct access to the .ini file is available here,
         though the :meth:`.Config.get_section` and
diff --git a/docs/build/api/autogenerate.rst b/docs/build/api/autogenerate.rst
index b96a299..b024ab1 100644
--- a/docs/build/api/autogenerate.rst
+++ b/docs/build/api/autogenerate.rst
@@ -1,10 +1,12 @@
+.. _alembic.autogenerate.toplevel:
+
 ==============
 Autogeneration
 ==============
 
 The autogenerate system has two areas of API that are public:
 
-1. The ability to do a "diff" of a :class:`.MetaData` object against
+1. The ability to do a "diff" of a :class:`~sqlalchemy.schema.MetaData` object against
    a database, and receive a data structure back.  This structure
    is available either as a rudimentary list of changes, or as
    a :class:`.MigrateOperation` structure.
diff --git a/docs/build/api/commands.rst b/docs/build/api/commands.rst
index 3d73ce5..65dcc09 100644
--- a/docs/build/api/commands.rst
+++ b/docs/build/api/commands.rst
@@ -1,10 +1,12 @@
+.. _alembic.command.toplevel:
+
 =========
 Commands
 =========
 
-Alembic commands are all represented by functions in the :mod:`alembic.command`
+Alembic commands are all represented by functions in the :ref:`alembic.command.toplevel`
 package.  They all accept the same style of usage, being sent
-the :class:`~.alembic.config.Config` object as the first argument.
+the :class:`.Config` object as the first argument.
 
 Commands can be run programmatically, by first constructing a :class:`.Config`
 object, as in::
@@ -32,7 +34,5 @@ information, rather than just running one of the built-in commands,
 use the :class:`.ScriptDirectory` and :class:`.MigrationContext`
 classes directly.
 
-.. currentmodule:: alembic.command
-
 .. automodule:: alembic.command
     :members:
diff --git a/docs/build/api/config.rst b/docs/build/api/config.rst
index 9294a6d..25d934f 100644
--- a/docs/build/api/config.rst
+++ b/docs/build/api/config.rst
@@ -1,3 +1,5 @@
+.. _alembic.config.toplevel:
+
 ==============
 Configuration
 ==============
@@ -10,7 +12,7 @@ it is needed for the following use cases:
   with the actual script files in a migration environment
 * to create an :class:`.EnvironmentContext`, which allows you to
   actually run the ``env.py`` module within the migration environment
-* to programatically run any of the commands in the :mod:`alembic.command`
+* to programatically run any of the commands in the :ref:`alembic.command.toplevel`
   module.
 
 The :class:`.Config` is *not* needed for these cases:
@@ -20,7 +22,5 @@ The :class:`.Config` is *not* needed for these cases:
 * to instantiate a :class:`.Operations` object - this object only
   needs a :class:`.MigrationContext`.
 
-.. currentmodule:: alembic.config
-
 .. automodule:: alembic.config
     :members:
diff --git a/docs/build/api/ddl.rst b/docs/build/api/ddl.rst
index aff697c..2d114c8 100644
--- a/docs/build/api/ddl.rst
+++ b/docs/build/api/ddl.rst
@@ -1,13 +1,15 @@
+.. _alembic.ddl.toplevel:
+
 =============
 DDL Internals
 =============
 
 These are some of the constructs used to generate migration
 instructions.  The APIs here build off of the :class:`sqlalchemy.schema.DDLElement`
-and :mod:`sqlalchemy.ext.compiler` systems.
+and :ref:`sqlalchemy.ext.compiler_toplevel` systems.
 
 For programmatic usage of Alembic's migration directives, the easiest
-route is to use the higher level functions given by :mod:`alembic.operations`.
+route is to use the higher level functions given by :ref:`alembic.operations.toplevel`.
 
 .. automodule:: alembic.ddl
     :members:
diff --git a/docs/build/api/environment.rst b/docs/build/api/environment.rst
index 874cf98..5a22773 100644
--- a/docs/build/api/environment.rst
+++ b/docs/build/api/environment.rst
@@ -1,3 +1,5 @@
+.. _alembic.runtime.environment.toplevel:
+
 =======================
 The Environment Context
 =======================
diff --git a/docs/build/api/index.rst b/docs/build/api/index.rst
index 26ee9b4..aa7c1a9 100644
--- a/docs/build/api/index.rst
+++ b/docs/build/api/index.rst
@@ -16,7 +16,7 @@ outside of this subsection, and the parameters that can be passed to
 the :meth:`.EnvironmentContext.configure` method, used when configuring
 one's ``env.py`` environment.  However, real-world applications will
 usually end up using more of the internal API, in particular being able
-to run commands programmatically, as discussed in the section :doc:`api/commands`.
+to run commands programmatically, as discussed in the section :doc:`/api/commands`.
 
 .. toctree::
    :maxdepth: 2
diff --git a/docs/build/api/migration.rst b/docs/build/api/migration.rst
index 300c792..ae74818 100644
--- a/docs/build/api/migration.rst
+++ b/docs/build/api/migration.rst
@@ -1,3 +1,5 @@
+.. _alembic.runtime.migration.toplevel:
+
 =====================
 The Migration Context
 =====================
diff --git a/docs/build/api/operations.rst b/docs/build/api/operations.rst
index 773cf6e..d9ff238 100644
--- a/docs/build/api/operations.rst
+++ b/docs/build/api/operations.rst
@@ -1,3 +1,5 @@
+.. _alembic.operations.toplevel:
+
 =====================
 The Operations Object
 =====================
@@ -13,7 +15,7 @@ Most methods on the :class:`.Operations` class are generated dynamically
 using a "plugin" system, described in the next section
 :ref:`operation_plugins`.   Additionally, when Alembic migration scripts
 actually run, the methods on the current :class:`.Operations` object are
-proxied out to the :mod:`alembic.op` module, so that they are available
+proxied out to the ``alembic.op`` module, so that they are available
 using module-style access.
 
 For an overview of how to use an :class:`.Operations` object directly
@@ -76,7 +78,7 @@ Above, we use the simplest possible technique of invoking our DDL, which
 is just to call :meth:`.Operations.execute` with literal SQL.  If this is
 all a custom operation needs, then this is fine.  However, options for
 more comprehensive support include building out a custom SQL construct,
-as documented at :ref:`sqlalchemy.ext.compiles`.
+as documented at :ref:`sqlalchemy.ext.compiler_toplevel`.
 
 With the above two steps, a migration script can now use a new method
 ``op.create_sequence()`` that will proxy to our object as a classmethod::
@@ -90,7 +92,7 @@ within the module level of the ``env.py`` script is sufficient.
 
 
 .. versionadded:: 0.8 - the migration operations available via the
-   :class:`.Operations` class as well as the :mod:`alembic.op` namespace
+   :class:`.Operations` class as well as the ``alembic.op`` namespace
    is now extensible using a plugin system.
 
 
@@ -115,5 +117,7 @@ autogenerate system renders new migration scripts.
 
 The built-in operation objects are listed below.
 
+.. _alembic.operations.ops.toplevel:
+
 .. automodule:: alembic.operations.ops
     :members:
diff --git a/docs/build/api/overview.rst b/docs/build/api/overview.rst
index 4bdbfa0..048d1e6 100644
--- a/docs/build/api/overview.rst
+++ b/docs/build/api/overview.rst
@@ -9,10 +9,10 @@ elements intended to convey the primary purpose of each system.
 
 .. image:: api_overview.png
 
-The script runner for Alembic is present in the :mod:`alembic.config` module.
+The script runner for Alembic is present in the :ref:`alembic.config.toplevel` module.
 This module produces a :class:`.Config` object and passes it to the
-appropriate function in :mod:`alembic.command`.   Functions within
-:mod:`alembic.command` will typically instantiate an
+appropriate function in :ref:`alembic.command.toplevel`.   Functions within
+:ref:`alembic.command.toplevel` will typically instantiate an
 :class:`.ScriptDirectory` instance, which represents the collection of
 version files, and an :class:`.EnvironmentContext`, which represents a
 configurational object passed to the environment's ``env.py`` script.
@@ -33,15 +33,15 @@ with the :class:`.ScriptDirectory`; the actual scripts themselves make use
 of the :class:`.Operations` object, which provide the end-user interface to
 specific database operations.   The :class:`.Operations` object is generated
 based on a series of "operation directive" objects that are user-extensible,
-and start out in the :mod:`alembic.operations.ops` module.
+and start out in the :ref:`alembic.operations.ops.toplevel` module.
 
 Another prominent feature of Alembic is the "autogenerate" feature, which
 produces new migration scripts that contain Python code.  The autogenerate
-feature starts in :mod:`alembic.autogenerate`, and is used exclusively
+feature starts in :ref:`alembic.autogenerate.toplevel`, and is used exclusively
 by the :func:`.alembic.command.revision` command when the ``--autogenerate``
 flag is passed.  Autogenerate refers to the :class:`.MigrationContext`
 and :class:`.DefaultImpl` in order to access database connectivity and
 access per-backend rules for autogenerate comparisons.  It also makes use
-of :mod:`alembic.operations.ops` in order to represent the operations that
+of :ref:`alembic.operations.ops.toplevel` in order to represent the operations that
 it will render into scripts.
 
diff --git a/docs/build/api/script.rst b/docs/build/api/script.rst
index 9ff7f2f..8dc594b 100644
--- a/docs/build/api/script.rst
+++ b/docs/build/api/script.rst
@@ -1,3 +1,5 @@
+.. _alembic.script.toplevel:
+
 ================
 Script Directory
 ================
diff --git a/docs/build/changelog.rst b/docs/build/changelog.rst
index 9c06825..7a96f8d 100644
--- a/docs/build/changelog.rst
+++ b/docs/build/changelog.rst
@@ -4,6 +4,44 @@ Changelog
 ==========
 
 .. changelog::
+    :version: 0.8.0
+
+    .. change::
+      :tags: feature, operations
+      :tickets: 302
+
+      The internal system for Alembic operations has been reworked to now
+      build upon an extensible system of operation objects.  New operations
+      can be added to the ``op.`` namespace, including that they are
+      available in custom autogenerate schemes.
+
+      .. seealso::
+
+          :ref:`operation_plugins`
+
+    .. change::
+      :tags: feature, autogenerate
+      :tickets: 301
+
+      The internal system for autogenerate been reworked to build upon
+      the extensible system of operation objects present in
+      :ticket:`302`.  As part of this change, autogenerate now produces
+      a full object graph representing a list of migration scripts to
+      be written as well as operation objects that will render all the
+      Python code within them; a new hook
+      :paramref:`.EnvironmentContext.configure.process_revision_directives`
+      allows end-user code to fully customize what autogenerate will do,
+      including not just full manipulation of the Python steps to take
+      but also what file or files will be written and where.  It is also
+      possible to write a system that reads an autogenerate stream and
+      invokes it directly against a database without writing any files.
+
+      .. seealso::
+
+        :ref:`alembic.autogenerate.toplevel`
+
+
+.. changelog::
     :version: 0.7.7
 
     .. change::
diff --git a/docs/build/cookbook.rst b/docs/build/cookbook.rst
index 8c1e0d7..541f595 100644
--- a/docs/build/cookbook.rst
+++ b/docs/build/cookbook.rst
@@ -193,7 +193,7 @@ Sharing a Connection with a Series of Migration Commands and Environments
 =========================================================================
 
 It is often the case that an application will need to call upon a series
-of commands within :mod:`alembic.command`, where it would be advantageous
+of commands within :ref:`alembic.command.toplevel`, where it would be advantageous
 for all operations to proceed along a single transaction.   The connectivity
 for a migration is typically solely determined within the ``env.py`` script
 of a migration environment, which is called within the scope of a command.
diff --git a/docs/build/front.rst b/docs/build/front.rst
index 3270f5c..6e28419 100644
--- a/docs/build/front.rst
+++ b/docs/build/front.rst
@@ -49,25 +49,19 @@ then proceed through the usage of this command.
 Dependencies
 ------------
 
-Alembic's install process will ensure that `SQLAlchemy <http://www.sqlalchemy.org>`_
+Alembic's install process will ensure that SQLAlchemy_
 is installed, in addition to other dependencies.  Alembic will work with
-SQLAlchemy as of version **0.7.3**.   The latest version of SQLAlchemy within
-the **0.7**, **0.8**, or more recent series is strongly recommended.
+SQLAlchemy as of version **0.7.3**, however more features are available with
+newer versions such as the 0.9 or 1.0 series.
 
 Alembic supports Python versions 2.6 and above.
 
-.. versionchanged:: 0.5.0
-	Support for SQLAlchemy 0.6 has been dropped.
-
-.. versionchanged:: 0.6.0
-	Now supporting Python 2.6 and above.
-
 Community
 =========
 
 Alembic is developed by `Mike Bayer <http://techspot.zzzeek.org>`_, and is
-loosely associated with the `SQLAlchemy <http://www.sqlalchemy.org/>`_ and `Pylons <http://www.pylonsproject.org>`_
-projects.
+loosely associated with the SQLAlchemy_, `Pylons <http://www.pylonsproject.org>`_,
+and `Openstack <http://www.openstack.org>`_ 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>`_.
@@ -78,3 +72,6 @@ Bugs
 ====
 Bugs and feature enhancements to Alembic should be reported on the `Bitbucket
 issue tracker <https://bitbucket.org/zzzeek/alembic/issues?status=new&status=open>`_.
+
+
+.. _SQLAlchemy: http://www.sqlalchemy.org
\ No newline at end of file
diff --git a/docs/build/ops.rst b/docs/build/ops.rst
index 83c936c..49aaef5 100644
--- a/docs/build/ops.rst
+++ b/docs/build/ops.rst
@@ -21,7 +21,7 @@ so symbols can be imported safely from the ``alembic.op`` namespace.
 The :class:`.Operations` system is also fully extensible.  See
 :ref:`operation_plugins` for details on this.
 
-A key design philosophy to the :mod:`alembic.operations` methods is that
+A key design philosophy to the :ref:`alembic.operations.toplevel` methods is that
 to the greatest degree possible, they internally generate the
 appropriate SQLAlchemy metadata, typically involving
 :class:`~sqlalchemy.schema.Table` and :class:`~sqlalchemy.schema.Constraint`
@@ -39,7 +39,5 @@ circumstances they are called from an actual migration script, which
 itself would be invoked by the :meth:`.EnvironmentContext.run_migrations`
 method.
 
-
 .. automodule:: alembic.operations
-    :members: Operations, BatchOperations
-
+	:members: Operations, BatchOperations