documentation including an API diagram

alembic/environment.py

@@ -5,7 +5,15 @@
 from contextlib import contextmanager
 
 class EnvironmentContext(object):
-    """Represent the state made available to an env.py script."""
+    """Represent the state made available to an ``env.py`` script.
+    
+    :class:`.EnvironmentContext` is normally instantiated
+    by the commands present in the :mod:`alembic.command`
+    module.  From within an ``env.py`` script, the current
+    :class:`.EnvironmentContext` is available via the 
+    ``alembic.context`` datamember.
+    
+    """
 
     _migration_context = None
     _default_opts = None
@@ -150,11 +158,20 @@ def configure(self,
             sqlalchemy_module_prefix="sa.",
             **kw
         ):
-        """Configure the migration environment.
-
-        The important thing needed here is first a way to figure out
-        what kind of "dialect" is in use.   The second is to pass
-        an actual database connection, if one is required.
+        """Configure a :class:`.MigrationContext` within this
+        :class:`.EnvironmentContext` which will provide database connectivity
+        and other configuration to a series of migration scripts.
+        
+        Many methods on :class:`.EnvironmentContext` require that 
+        this method has been called in order to function, as they
+        ultimately need to have database access or at least access
+        to the dialect in use.  Those which do are documented as such.
+        
+        The important thing needed by :meth:`.configure` is a
+        means to determine what kind of database dialect is in use.  
+        An actual connection to that database is needed only if
+        the :class:`.MigrationContext` is to be used in 
+        "online" mode.
 
         If the :meth:`.is_offline_mode` function returns ``True``,
         then no connection is needed here.  Otherwise, the
@@ -420,11 +437,6 @@ def migration_context(self):
         If :meth:`.EnvironmentContext.configure` has not been called yet, raises
         an exception.
 
-        Generally, env.py scripts should access this via
-        the ``alembic.context`` object, which is an instance of
-        :class:`.MigrationContext` placed there for the duration 
-        of the env.py script's usage.
-
         """
         if self._migration_context is None:
             raise Exception("No context has been configured yet.")

alembic/operations.py

@@ -13,9 +13,23 @@ class Operations(object):
     Each operation corresponds to some schema migration operation,
     executed against a particular :class:`.MigrationContext`.
     
+    Normally, the :class:`.MigrationContext` is created
+    within an ``env.py`` script via the
+    :meth:`.EnvironmentContext.configure` method.  However,
+    the :class:`.Operations` object can also be used without
+    actually using the :class:`.EnvironmentContext` 
+    class - only :class:`.MigrationContext`, which represents
+    connectivity to a single database, is needed
+    to use the directives.
+    
     """
     def __init__(self, migration_context):
-        """Construct a new :class:`.Operations`"""
+        """Construct a new :class:`.Operations`
+        
+        :param migration_context: a :class:`.MigrationContext` 
+         instance.
+         
+        """
         self.migration_context = migration_context
         self.impl = migration_context.impl
 

docs/build/api.rst

@@ -5,18 +5,51 @@ API Details
 This section describes some key functions used within the migration process, particularly those referenced within
 a migration environment's ``env.py`` file.
 
+Overview
+========
+
+The three main objects in use are the :class:`.EnvironmentContext`, :class:`.MigrationContext`,
+and :class:`.Operations` classes, pictured below.
+
+.. image:: api_overview.png
+
+An Alembic command begins by instantiating an :class:`.EnvironmentContext` object, then
+making it available via the ``alembic.context`` datamember.  The ``env.py``
+script, representing a user-configurable migration environment, is then 
+invoked.   The ``env.py`` script is then responsible for calling upon the
+:meth:`.EnvironmentContext.configure`, whose job it is to create 
+a :class:`.MigrationContext` object. 
+
+Before this method is called, there's not
+yet any database connection or dialect-specific state set up.  While 
+many methods on :class:`.EnvironmentContext` are usable at this stage,
+those which require database access, or at least access to the kind 
+of database dialect in use, are not.   Once the 
+:meth:`.EnvironmentContext.configure` method is called, the :class:`.EnvironmentContext`
+is said to be *configured* with database connectivity, available via
+a new :class:`.MigrationContext` object.   The :class:`.MigrationContext`
+is associated with the :class:`.EnvironmentContext` object
+via the :attr:`.EnvironmentContext.migration_context` datamember.
+
+Finally, ``env.py`` calls upon the :meth:`.EnvironmentContext.run_migrations`
+method.   Within this method, a new :class:`.Operations` object, which
+provides an API for individual database migration operations, is established
+within the ``alembic.op`` datamember.   The :class:`.Operations` object
+uses the :class:`.MigrationContext` object ultimately as a source of 
+database connectivity, though in such a way that it does not care if the
+:class:`.MigrationContext` is talking to a real database or just writing
+out SQL to a file.
+
 env.py Directives
 =================
 
-The :mod:`alembic.environment` module contains API features that are generally used within
-``env.py`` files.
+This section covers the objects that are generally used within an 
+``env.py`` environmental configuration script.   Alembic normally generates
+this script for you; it is however made available locally within the migrations
+environment so that it can be customized.
 
-The central object in use is the :class:`.EnvironmentContext` object.   This object is 
-made present when the ``env.py`` script calls upon the :meth:`.EnvironmentContext.configure`
-method for the first time.  Before this function is called, there's not
-yet any database connection or dialect-specific state set up, and those
-functions which require this state will raise an exception when used,
-until :meth:`.EnvironmentContext.configure` is called successfully.
+In particular, the key method used within ``env.py`` is :meth:`.EnvironmentContext.configure`,
+which establishes all the details about how the database will be accessed.
 
 
 .. autofunction:: sqlalchemy.engine.engine_from_config
@@ -27,7 +60,6 @@ until :meth:`.EnvironmentContext.configure` is called successfully.
 .. automodule:: alembic.migration
     :members:
 
-
 Commands
 =========