- provide param docstrings for all of command

- add cross-linking for process_revision_directives

Change-Id: I88914df056d720207c781501934893ec8e030610

3 files changed, 161 insertions, 13 deletions

diff --git a/alembic/command.py b/alembic/command.py
index 9a333a0..694ee3f 100644
--- a/alembic/command.py
+++ b/alembic/command.py
@@ -7,7 +7,11 @@ from . import autogenerate as autogen
 
 
 def list_templates(config):
-    """List available templates"""
+    """List available templates
+
+    :param config: a :class:`.Config` object.
+
+    """
 
     config.print_stdout("Available templates:\n")
     for tempname in os.listdir(config.get_template_directory()):
@@ -23,7 +27,16 @@ def list_templates(config):
 
 
 def init(config, directory, template='generic'):
-    """Initialize a new scripts directory."""
+    """Initialize a new scripts directory.
+
+    :param config: a :class:`.Config` object.
+
+    :param directory: string path of the target directory
+
+    :param template: string name of the migration environment template to
+     use.
+
+    """
 
     if os.access(directory, os.F_OK):
         raise util.CommandError("Directory %s already exists" % directory)
@@ -70,7 +83,51 @@ def revision(
         head="head", splice=False, branch_label=None,
         version_path=None, rev_id=None, depends_on=None,
         process_revision_directives=None):
-    """Create a new revision file."""
+    """Create a new revision file.
+
+    :param config: a :class:`.Config` object.
+
+    :param message: string message to apply to the revision; this is the
+     ``-m`` option to ``alembic revision``.
+
+    :param autogenerate: whether or not to autogenerate the script from
+     the database; this is the ``--autogenerate`` option to ``alembic revision``.
+
+    :param sql: whether to dump the script out as a SQL string; when specified,
+     the script is dumped to stdout.  This is the ``--sql`` option to
+     ``alembic revision``.
+
+    :param head: head revision to build the new revision upon as a parent;
+     this is the ``--head`` option to ``alembic revision``.
+
+    :param splice: whether or not the new revision should be made into a
+     new head of its own; is required when the given ``head`` is not itself
+     a head.  This is the ``--splice`` option to ``alembic revision``.
+
+    :param branch_label: string label to apply to the branch; this is the
+     ``--branch-label`` option to ``alembic revision``.
+
+    :param version_path: string symbol identifying a specific version path
+     from the configuration; this is the ``--version-path`` option to
+     ``alembic revision``.
+
+    :param rev_id: optional revision identifier to use instead of having
+     one generated; this is the ``--rev-id`` option to ``alembic revision``.
+
+    :param depends_on: optional list of "depends on" identifiers; this is the
+     ``--depends-on`` option to ``alembic revision``.
+
+    :param process_revision_directives: this is a callable that takes the
+     same form as the callable described at
+     :paramref:`.EnvironmentContext.configure.process_revision_directives`;
+     will be applied to the structure generated by the revision process
+     where it can be altered programmatically.   Note that unlike all
+     the other parameters, this option is only available via programmatic
+     use of :func:`.command.revision`
+
+     .. versionadded:: 0.9.0
+
+    """
 
     script_directory = ScriptDirectory.from_config(config)
 
@@ -133,6 +190,15 @@ def merge(config, revisions, message=None, branch_label=None, rev_id=None):
 
     .. versionadded:: 0.7.0
 
+    :param config: a :class:`.Config` instance
+
+    :param message: string message to apply to the revision
+
+    :param branch_label: string label name to apply to the new revision
+
+    :param rev_id: hardcoded revision identifier instead of generating a new
+     one.
+
     .. seealso::
 
         :ref:`branches`
@@ -151,7 +217,19 @@ def merge(config, revisions, message=None, branch_label=None, rev_id=None):
 
 
 def upgrade(config, revision, sql=False, tag=None):
-    """Upgrade to a later version."""
+    """Upgrade to a later version.
+
+    :param config: a :class:`.Config` instance.
+
+    :param revision: string revision target or range for --sql mode
+
+    :param sql: if True, use ``--sql`` mode
+
+    :param tag: an arbitrary "tag" that can be intercepted by custom
+     ``env.py`` scripts via the :class:`.EnvironmentContext.get_tag_argument`
+     method.
+
+    """
 
     script = ScriptDirectory.from_config(config)
 
@@ -177,7 +255,19 @@ def upgrade(config, revision, sql=False, tag=None):
 
 
 def downgrade(config, revision, sql=False, tag=None):
-    """Revert to a previous version."""
+    """Revert to a previous version.
+
+    :param config: a :class:`.Config` instance.
+
+    :param revision: string revision target or range for --sql mode
+
+    :param sql: if True, use ``--sql`` mode
+
+    :param tag: an arbitrary "tag" that can be intercepted by custom
+     ``env.py`` scripts via the :class:`.EnvironmentContext.get_tag_argument`
+     method.
+
+    """
 
     script = ScriptDirectory.from_config(config)
     starting_rev = None
@@ -205,7 +295,13 @@ def downgrade(config, revision, sql=False, tag=None):
 
 
 def show(config, rev):
-    """Show the revision(s) denoted by the given symbol."""
+    """Show the revision(s) denoted by the given symbol.
+
+    :param config: a :class:`.Config` instance.
+
+    :param revision: string revision target
+
+    """
 
     script = ScriptDirectory.from_config(config)
 
@@ -226,7 +322,15 @@ def show(config, rev):
 
 
 def history(config, rev_range=None, verbose=False):
-    """List changeset scripts in chronological order."""
+    """List changeset scripts in chronological order.
+
+    :param config: a :class:`.Config` instance.
+
+    :param rev_range: string revision range
+
+    :param verbose: output in verbose mode.
+
+    """
 
     script = ScriptDirectory.from_config(config)
     if rev_range is not None:
@@ -271,7 +375,15 @@ def history(config, rev_range=None, verbose=False):
 
 
 def heads(config, verbose=False, resolve_dependencies=False):
-    """Show current available heads in the script directory"""
+    """Show current available heads in the script directory
+
+    :param config: a :class:`.Config` instance.
+
+    :param verbose: output in verbose mode.
+
+    :param resolve_dependencies: treat dependency version as down revisions.
+
+    """
 
     script = ScriptDirectory.from_config(config)
     if resolve_dependencies:
@@ -286,7 +398,13 @@ def heads(config, verbose=False, resolve_dependencies=False):
 
 
 def branches(config, verbose=False):
-    """Show current branch points"""
+    """Show current branch points.
+
+    :param config: a :class:`.Config` instance.
+
+    :param verbose: output in verbose mode.
+
+    """
     script = ScriptDirectory.from_config(config)
     for sc in script.walk_revisions():
         if sc.is_branch_point:
@@ -305,7 +423,15 @@ def branches(config, verbose=False):
 
 
 def current(config, verbose=False, head_only=False):
-    """Display the current revision for a database."""
+    """Display the current revision for a database.
+
+    :param config: a :class:`.Config` instance.
+
+    :param verbose: output in verbose mode.
+
+    :param head_only: deprecated; use ``verbose`` for additional output.
+
+    """
 
     script = ScriptDirectory.from_config(config)
 
@@ -333,7 +459,19 @@ def current(config, verbose=False, head_only=False):
 
 def stamp(config, revision, sql=False, tag=None):
     """'stamp' the revision table with the given revision; don't
-    run any migrations."""
+    run any migrations.
+
+    :param config: a :class:`.Config` instance.
+
+    :param revision: target revision.
+
+    :param sql: use ``--sql`` mode
+
+    :param tag: an arbitrary "tag" that can be intercepted by custom
+     ``env.py`` scripts via the :class:`.EnvironmentContext.get_tag_argument`
+     method.
+
+    """
 
     script = ScriptDirectory.from_config(config)
 
@@ -359,7 +497,13 @@ def stamp(config, revision, sql=False, tag=None):
 
 
 def edit(config, rev):
-    """Edit revision script(s) using $EDITOR"""
+    """Edit revision script(s) using $EDITOR.
+
+    :param config: a :class:`.Config` instance.
+
+    :param rev: target revision.
+
+    """
 
     script = ScriptDirectory.from_config(config)
 
diff --git a/alembic/runtime/environment.py b/alembic/runtime/environment.py
index 4d33f0a..edabc06 100644
--- a/alembic/runtime/environment.py
+++ b/alembic/runtime/environment.py
@@ -730,6 +730,8 @@ class EnvironmentContext(util.ModuleClsProxy):
 
              :ref:`autogen_rewriter`
 
+             :paramref:`.command.revision.process_revision_directives`
+
 
         Parameters specific to individual backends:
 
diff --git a/docs/build/changelog.rst b/docs/build/changelog.rst
index 0b46a48..eaf9c65 100644
--- a/docs/build/changelog.rst
+++ b/docs/build/changelog.rst
@@ -68,7 +68,9 @@ Changelog
 
       Added a keyword argument ``process_revision_directives`` to the
       :func:`.command.revision` API call.  This function acts in the
-      same role as the environment-level call, and allows API use of the
+      same role as the environment-level
+      :paramref:`.EnvironmentContext.configure.process_revision_directives`,
+      and allows API use of the
       command to drop in an ad-hoc directive process function.  This
       function can be used among other things to place a complete
       :class:`.MigrationScript` structure in place.