- since the section titles in api are bound to be misleading,

put notes at the top of most of them
- consolidate EnvironmentContext / MigrationContext

8 files changed, 52 insertions, 10 deletions

diff --git a/docs/build/api/autogenerate.rst b/docs/build/api/autogenerate.rst
index 8b026e8..7376915 100644
--- a/docs/build/api/autogenerate.rst
+++ b/docs/build/api/autogenerate.rst
@@ -4,6 +4,13 @@
 Autogeneration
 ==============
 
+.. note:: this section discusses the **internal API of Alembic**
+   as regards the autogeneration feature of the ``alembic revision``
+   command.
+   This section is only useful for developers who wish to extend the
+   capabilities of Alembic.  For general documentation on the autogenerate
+   feature, please see :doc:`/autogenerate`.
+
 The autogeneration system has a wide degree of public API, including
 the following areas:
 
diff --git a/docs/build/api/commands.rst b/docs/build/api/commands.rst
index 65dcc09..266a206 100644
--- a/docs/build/api/commands.rst
+++ b/docs/build/api/commands.rst
@@ -4,6 +4,12 @@
 Commands
 =========
 
+.. note:: this section discusses the **internal API of Alembic**
+   as regards its command invocation system.
+   This section is only useful for developers who wish to extend the
+   capabilities of Alembic.  For documentation on using Alembic commands,
+   please see :doc:`/tutorial`.
+
 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:`.Config` object as the first argument.
diff --git a/docs/build/api/config.rst b/docs/build/api/config.rst
index 25d934f..1d1181b 100644
--- a/docs/build/api/config.rst
+++ b/docs/build/api/config.rst
@@ -4,6 +4,12 @@
 Configuration
 ==============
 
+.. note:: this section discusses the **internal API of Alembic** as
+   regards internal configuration constructs.
+   This section is only useful for developers who wish to extend the
+   capabilities of Alembic.  For documentation on configuration of
+   an Alembic environment, please see :doc:`/tutorial`.
+
 The :class:`.Config` object represents the configuration
 passed to the Alembic environment.  From an API usage perspective,
 it is needed for the following use cases:
diff --git a/docs/build/api/index.rst b/docs/build/api/index.rst
index aa7c1a9..f9efb89 100644
--- a/docs/build/api/index.rst
+++ b/docs/build/api/index.rst
@@ -22,8 +22,7 @@ to run commands programmatically, as discussed in the section :doc:`/api/command
    :maxdepth: 2
 
    overview
-   environment
-   migration
+   runtime
    config
    commands
    operations
diff --git a/docs/build/api/migration.rst b/docs/build/api/migration.rst
deleted file mode 100644
index ae74818..0000000
--- a/docs/build/api/migration.rst
+++ /dev/null
@@ -1,8 +0,0 @@
-.. _alembic.runtime.migration.toplevel:
-
-=====================
-The Migration Context
-=====================
-
-.. automodule:: alembic.runtime.migration
-    :members: MigrationContext
diff --git a/docs/build/api/operations.rst b/docs/build/api/operations.rst
index 2eb8358..e55b958 100644
--- a/docs/build/api/operations.rst
+++ b/docs/build/api/operations.rst
@@ -4,6 +4,12 @@
 Operation Directives
 =====================
 
+.. note:: this section discusses the **internal API of Alembic** as regards
+   the internal system of defining migration operation directives.
+   This section is only useful for developers who wish to extend the
+   capabilities of Alembic.  For end-user guidance on Alembic migration
+   operations, please see :ref:`ops`.
+
 Within migration scripts, actual database migration operations are handled
 via an instance of :class:`.Operations`.   The :class:`.Operations` class
 lists out available migration operations that are linked to a
diff --git a/docs/build/api/overview.rst b/docs/build/api/overview.rst
index 3e6bec8..94c1f85 100644
--- a/docs/build/api/overview.rst
+++ b/docs/build/api/overview.rst
@@ -2,6 +2,12 @@
 Overview
 ========
 
+.. note:: this section is a technical overview of the
+   **internal API of Alembic**.
+   This section is only useful for developers who wish to extend the
+   capabilities of Alembic; for regular users, reading this section
+   is **not necessary**.
+
 A visualization of the primary features of Alembic's internals is presented
 in the following figure.   The module and class boxes do not list out
 all the operations provided by each unit; only a small set of representative
diff --git a/docs/build/api/environment.rst b/docs/build/api/runtime.rst
index 5a22773..f32e943 100644
--- a/docs/build/api/environment.rst
+++ b/docs/build/api/runtime.rst
@@ -1,6 +1,14 @@
 .. _alembic.runtime.environment.toplevel:
 
 =======================
+Runtime Objects
+=======================
+
+The "runtime" of Alembic involves the :class:`.EnvironmentContext`
+and :class:`.MigrationContext` objects.   These are the objects that are
+in play once the ``env.py`` script is loaded up by a command and
+a migration operation proceeds.
+
 The Environment Context
 =======================
 
@@ -17,3 +25,15 @@ which establishes all the details about how the database will be accessed.
 
 .. automodule:: alembic.runtime.environment
     :members: EnvironmentContext
+
+.. _alembic.runtime.migration.toplevel:
+
+The Migration Context
+=====================
+
+The :class:`.MigrationContext` handles the actual work to be performed
+against a database backend as migration operations proceed.  It is generally
+not exposed to the end-user.
+
+.. automodule:: alembic.runtime.migration
+    :members: MigrationContext