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

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

diff --git a/docs/build/api/autogenerate.rst b/docs/build/api/autogenerate.rst
index 8b026e81cadc4b7e1dbd1591e5b4f9cec45a5fa9..7376915ef6e44e44f1b661c339fbac99cd3d2ea3 100644 (file)
--- 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 65dcc09566512b4088bf8c7b847d05e03ed86b92..266a20660d6e8de99cd09e9ce73b6b606d4a0351 100644 (file)
--- 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 25d934fbf70219f86610643aa8ef0eefa8629dea..1d1181b9a74abf619b5945376afd04c9fe16482c 100644 (file)
--- 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 aa7c1a9e3eaeb7242854f4882c292863ad5f4ff0..f9efb899a7468c6e9e68e701c488c5fb827249b8 100644 (file)
--- 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 (file)
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 2eb8358e734fcf593ec21161f7c0c74797c93903..e55b958b7fec584fb31aaf77ecb6a98c1bdcbc7b 100644 (file)
--- 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 3e6bec83f7ce7afa7502b5f79a2721528d6909c9..94c1f8584bab095ee3ddbbfd72f39e90909ff9ba 100644 (file)
--- 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
similarity index 56%
rename from docs/build/api/environment.rst
rename to docs/build/api/runtime.rst
index 5a227738c4ecd8a1047db07134337a4449725421..f32e943a4e81faeb583a51f0abda8a0dad7ae34a 100644 (file)
--- 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