Updated docs

ckan/plugins/interfaces.py

@@ -1558,12 +1558,37 @@ def get_resource_uploader(self):
 
 
 class IMigration(Interface):
+    ''' This interface allows extensions to provide migrations.
+
+    By providing migrations, extension specific database tables will be
+    kept up to date whenever ```paster db upgrade``` is run.
+    '''
 
     def migrations(self):
         '''Returns the repository name for the migrations.
 
           This should be a / separated string specifying a path to a module.
           For instance, in ckan this is 'ckan/migrations'.  In an extension called
-          my_extension it would be 'my_extension/migrations' if the migrations
-          folder contains versions folder.
+          my_extension it would be '/full/path/to/my_extension/migrations' to
+          ensure the migrations can be found from within the ckan plugin.
+
+          The folder structure for migrations is fairly specific and should be
+          structured as:
+
+                ckanext/myext/migrations/
+                ckanext/myext/migrations/__init__.py
+                ckanext/myext/migrations/migrate.cfg
+                ckanext/myext/migrations/versions/
+                ckanext/myext/migrations/versions/__init__.py
+
+           Each migration should them be a python file named with an
+           incrementing counter as part of the filename.  The first migration
+           would be 001_add_tables.py, the second 002_update_tables.py.
+
+           The migrate.cfg file, should follow the layout below:
+
+                [db_settings]
+                repository_id=ckanext-myext
+                version_table=migrate_version
+                required_dbs=[]
         '''

doc/extensions/tutorial.rst

@@ -71,6 +71,11 @@ to get you started::
             __init__.py
             iauthfunctions/
                 __init__.py
+                migrations/
+                    __init__.py
+                    versions/
+                        __init__.py
+                        001_initial_creation.py
         ckanext_iauthfunctions.egg-info/
         setup.py
 
@@ -83,6 +88,10 @@ this directory, and you should not add it to version control.
 this script to install your project into a virtual environment. It contains
 several settings that you'll update as you develop your project.
 
+``ckanext/iauthfunctions/migrations/versions`` is the module which will contain
+any database migrations that you wish to use to build and migrate database
+tables.
+
 ``ckanext/iauthfunctions`` is the Python package directory where we'll add the
 source code files for our extension.