update sqlalchemy documentation links

use explicit code-block markup

1 files changed, 125 insertions, 98 deletions

diff --git a/docs/changeset.rst b/docs/changeset.rst
index 0ab0b2b..1ae070e 100644
--- a/docs/changeset.rst
+++ b/docs/changeset.rst
@@ -7,19 +7,18 @@ Database schema migrations
 
 .. currentmodule:: migrate.changeset.schema
 
-Importing :mod:`migrate.changeset` adds some new methods to existing
-SQLAlchemy objects, as well as creating functions of its own. Most operations
-can be done either by a method or a function. Methods match
-SQLAlchemy's existing API and are more intuitive when the object is
-available; functions allow one to make changes when only the name of
-an object is available (for example, adding a column to a table in the
-database without having to load that table into Python).
+Importing :mod:`migrate.changeset` adds some new methods to existing SQLAlchemy
+objects, as well as creating functions of its own. Most operations can be done
+either by a method or a function. Methods match SQLAlchemy's existing API and
+are more intuitive when the object is available; functions allow one to make
+changes when only the name of an object is available (for example, adding a
+column to a table in the database without having to load that table into
+Python).
 
 Changeset operations can be used independently of SQLAlchemy Migrate's
 :ref:`versioning <versioning-system>`.
 
-For more information, see the API documentation for
-:mod:`migrate.changeset`.
+For more information, see the API documentation for :mod:`migrate.changeset`.
 
 .. _summary-changeset-api:
 
@@ -43,69 +42,76 @@ Here are some direct links to the relevent sections of the API documentations:
 
 .. note::
 
-  Many of the schema modification methods above take an
-  ``alter_metadata`` keyword parameter. This parameter defaults to
-  ``True``.
+  Many of the schema modification methods above take an ``alter_metadata``
+  keyword parameter. This parameter defaults to `True`.
 
-The following sections give examples of how to make various kinds of
-schema changes.
+The following sections give examples of how to make various kinds of schema
+changes.
 
 Column
 ======
 
-Given a standard SQLAlchemy table::
+Given a standard SQLAlchemy table:
 
- table = Table('mytable', meta,
-    Column('id', Integer, primary_key=True),
- )
- table.create()
+.. code-block:: python
+
+    table = Table('mytable', meta,
+        Column('id', Integer, primary_key=True),
+    )
+    table.create()
 
 .. _column-create:
 
-You can create a column with :meth:`~ChangesetColumn.create`::
+You can create a column with :meth:`~ChangesetColumn.create`:
+
+.. code-block:: python
 
- col = Column('col1', String, default='foobar')
- col.create(table, populate_default=True)
+    col = Column('col1', String, default='foobar')
+    col.create(table, populate_default=True)
 
- # Column is added to table based on its name
- assert col is table.c.col1
+    # Column is added to table based on its name
+    assert col is table.c.col1
 
- # col1 is populated with 'foobar' because of `populate_default`
+    # col1 is populated with 'foobar' because of `populate_default`
 
 .. _column-drop:
 
 .. note::
 
-  You can pass `primary_key_name`, `index_name`
-  and `unique_name` to the :meth:`~ChangesetColumn.create` method to issue ``ALTER TABLE ADD
+  You can pass `primary_key_name`, `index_name` and `unique_name` to the
+  :meth:`~ChangesetColumn.create` method to issue ``ALTER TABLE ADD
   CONSTRAINT`` after changing the column. 
 
-  For multi columns constraints and other advanced configuration,
-  check the :ref:`constraint tutorial <constraint-tutorial>`. 
+  For multi columns constraints and other advanced configuration, check the
+  :ref:`constraint tutorial <constraint-tutorial>`. 
 
   .. versionadded:: 0.6.0
 
-You can drop a column with :meth:`~ChangesetColumn.drop`::
+You can drop a column with :meth:`~ChangesetColumn.drop`:
+
+.. code-block:: python
 
- col.drop()
+    col.drop()
 
 
 .. _column-alter:
 
-You can alter a column with :meth:`~ChangesetColumn.alter`::
+You can alter a column with :meth:`~ChangesetColumn.alter`:
 
- col.alter(name='col2')
+.. code-block:: python
 
- # Renaming a column affects how it's accessed by the table object
- assert col is table.c.col2
+    col.alter(name='col2')
 
- # Other properties can be modified as well
- col.alter(type=String(42), default="life, the universe, and everything", nullable=False)
+    # Renaming a column affects how it's accessed by the table object
+    assert col is table.c.col2
 
- # Given another column object, col1.alter(col2), col1 will be changed to match col2
- col.alter(Column('col3', String(77), nullable=True))
- assert col.nullable
- assert table.c.col3 is col
+    # Other properties can be modified as well
+    col.alter(type=String(42), default="life, the universe, and everything", nullable=False)
+
+    # Given another column object, col1.alter(col2), col1 will be changed to match col2
+    col.alter(Column('col3', String(77), nullable=True))
+    assert col.nullable
+    assert table.c.col3 is col
 
 .. deprecated:: 0.6.0
     Passing a :class:`~sqlalchemy.schema.Column` to
@@ -121,11 +127,13 @@ Table
 
 SQLAlchemy includes support for `creating and dropping`__ tables..
 
-Tables can be renamed with :meth:`~ChangesetTable.rename`::
+Tables can be renamed with :meth:`~ChangesetTable.rename`:
+
+.. code-block:: python
 
- table.rename('newtablename')
+    table.rename('newtablename')
 
-.. __: http://www.sqlalchemy.org/docs/05/metadata.html#creating-and-dropping-database-tables
+.. __: http://www.sqlalchemy.org/docs/core/schema.html#creating-and-dropping-database-tables
 .. currentmodule:: migrate.changeset.constraint
 
 
@@ -136,11 +144,14 @@ Index
 
 SQLAlchemy supports `creating and dropping`__ indexes.
 
-Indexes can be renamed using :meth:`~migrate.changeset.schema.ChangesetIndex.rename`::
+Indexes can be renamed using
+:meth:`~migrate.changeset.schema.ChangesetIndex.rename`:
+
+.. code-block:: python
 
- index.rename('newindexname')
+    index.rename('newindexname')
 
-.. __: http://www.sqlalchemy.org/docs/05/metadata.html#indexes
+.. __: http://www.sqlalchemy.org/docs/core/schema.html#indexes
 
 
 .. _constraint-tutorial:
@@ -150,29 +161,33 @@ Constraint
 
 .. currentmodule:: migrate.changeset.constraint
 
-SQLAlchemy supports creating or dropping constraints at the same time
-a table is created or dropped. SQLAlchemy Migrate adds support for
-creating and dropping
-:class:`~sqlalchemy.schema.PrimaryKeyConstraint`,
+SQLAlchemy supports creating or dropping constraints at the same time a table
+is created or dropped. SQLAlchemy Migrate adds support for creating and
+dropping :class:`~sqlalchemy.schema.PrimaryKeyConstraint`,
 :class:`~sqlalchemy.schema.ForeignKeyConstraint`,
 :class:`~sqlalchemy.schema.CheckConstraint` and
-:class:`~sqlalchemy.schema.UniqueConstraint` constraints independently
-using ``ALTER TABLE`` statements.
+:class:`~sqlalchemy.schema.UniqueConstraint` constraints independently using
+``ALTER TABLE`` statements.
 
 The following rundowns are true for all constraints classes:
 
-1. Make sure you import the relevent constrain class Migrate and not
-   from SQLAlchemy, for example::
+#. Make sure you import the relevant constraint class from :mod:`migrate` and
+   not from :mod:`sqlalchemy`, for example:
 
-    from migrate.changeset.constraint import ForeignKeyConstraint
+   .. code-block:: python
+
+        from migrate.changeset.constraint import ForeignKeyConstraint
 
    The classes in that module have the extra
-   :meth:`~ConstraintChangeset.create` and
-   :meth:`~ConstraintChangeset.drop` methods.
+   :meth:`~ConstraintChangeset.create` and :meth:`~ConstraintChangeset.drop`
+   methods.
+
+#. You can also use constraints as in SQLAlchemy. In this case passing table
+   argument explicitly is required:
 
-2. You can also use Constraints as in SQLAlchemy. In this case passing table argument explicitly is required::
+   .. code-block:: python
 
-	cons = PrimaryKeyConstraint('id', 'num', table=self.table)
+        cons = PrimaryKeyConstraint('id', 'num', table=self.table)
 
 	# Create the constraint
 	cons.create()
@@ -180,11 +195,16 @@ The following rundowns are true for all constraints classes:
 	# Drop the constraint
 	cons.drop()
 
-   You can also pass in :class:`~sqlalchemy.schema.Column` objects (and table argument can be left out)::
+   You can also pass in :class:`~sqlalchemy.schema.Column` objects (and table
+   argument can be left out):
+
+   .. code-block:: python
 
 	cons = PrimaryKeyConstraint(col1, col2)
 
-3. Some dialects support ``CASCADE`` option when dropping constraints::
+#. Some dialects support ``CASCADE`` option when dropping constraints:
+
+    .. code-block:: python
 
 	cons = PrimaryKeyConstraint(col1, col2)
 
@@ -194,62 +214,69 @@ The following rundowns are true for all constraints classes:
 	# Drop the constraint
 	cons.drop(cascade=True)
 
-
 .. note::
-	 SQLAlchemy Migrate will try to guess the name of the
-	 constraints for databases, but if it's something other than
-	 the default, you'll need to give its name. Best practice is
-	 to always name your constraints. Note that Oracle requires
-	 that you state the name of the constraint to be created or dropped.
+    SQLAlchemy Migrate will try to guess the name of the constraints for
+    databases, but if it's something other than the default, you'll need to
+    give its name. Best practice is to always name your constraints. Note that
+    Oracle requires that you state the name of the constraint to be created or
+    dropped.
 
 
 Examples
 ---------
 
-Primary key constraints::
+Primary key constraints:
 
- from migrate.changeset.constraint import PrimaryKeyConstraint
+.. code-block:: python
 
- cons = PrimaryKeyConstraint(col1, col2)
+    from migrate.changeset.constraint import PrimaryKeyConstraint
 
- # Create the constraint
- cons.create()
+    cons = PrimaryKeyConstraint(col1, col2)
 
- # Drop the constraint
- cons.drop()
+    # Create the constraint
+    cons.create()
 
-Foreign key constraints::
+    # Drop the constraint
+    cons.drop()
 
- from migrate.changeset.constraint import ForeignKeyConstraint
+Foreign key constraints:
 
- cons = ForeignKeyConstraint([table.c.fkey], [othertable.c.id])
+.. code-block:: python
 
- # Create the constraint
- cons.create()
-
- # Drop the constraint
- cons.drop()
+    from migrate.changeset.constraint import ForeignKeyConstraint
+    
+    cons = ForeignKeyConstraint([table.c.fkey], [othertable.c.id])
+    
+    # Create the constraint
+    cons.create()
+    
+    # Drop the constraint
+    cons.drop()
 
-Check constraints::
+Check constraints:
 
-	from migrate.changeset.constraint import CheckConstraint
+.. code-block:: python
 
-	cons = CheckConstraint('id > 3', columns=[table.c.id])
+    from migrate.changeset.constraint import CheckConstraint
+    
+    cons = CheckConstraint('id > 3', columns=[table.c.id])
+    
+    # Create the constraint
+    cons.create()
 
-	# Create the constraint
-	cons.create()
+    # Drop the constraint
+    cons.drop()
 
-	# Drop the constraint
-	cons.drop()
+Unique constraints:
 
-Unique constraints::
+.. code-block:: python
 
-	from migrate.changeset.constraint import UniqueConstraint
+    from migrate.changeset.constraint import UniqueConstraint
+    
+    cons = UniqueConstraint('id', 'age', table=self.table)
 
-	cons = UniqueConstraint('id', 'age', table=self.table)
+    # Create the constraint
+    cons.create()
 
-	# Create the constraint
-	cons.create()
-
-	# Drop the constraint
-	cons.drop()
+    # Drop the constraint
+    cons.drop()