updates to docs

- updated links
- removed trailing spaces
- added tags to make code blocks explicitly python code
- removed inline code markups that weren't actually code

docs/source/api.rst

@@ -6,7 +6,7 @@ ColanderAlchemy API
 .. automodule:: colanderalchemy
 
   .. autoclass:: SQLAlchemySchemaNode
-  
+
      .. automethod:: __init__
      .. automethod:: dictify
      .. automethod:: objectify

docs/source/customization.rst

@@ -10,46 +10,47 @@ The default ``Colander`` schema generated using
 :class:`colanderalchemy.SQLAlchemySchemaNode` follows certain rules seen in
 :ref:`how_it_works`.  You can change the default behaviour of
 :class:`colanderalchemy.SQLAlchemySchemaNode` by specifying the keyword
-arguments ``includes``, ``excludes``, and ``overrides``.  
+arguments ``includes``, ``excludes``, and ``overrides``.
 
 Refer to the API for :class:`colanderalchemy.SQLAlchemySchemaNode` and the
 `tests
 <https://github.com/stefanofontanelli/ColanderAlchemy/tree/master/tests>`_
 to understand how they work.
 
 This class also accepts all keyword arguments that could normally be passed to
-a basic :class:`colander.SchemaNode`, such as `title`, `description`,
-`preparer`, and more. Read more about basic Colander customisation at
+a basic :class:`colander.SchemaNode`, such as ``title``, ``description``,
+``preparer``, and more. Read more about basic Colander customisation at
 http://docs.pylonsproject.org/projects/colander/en/latest/basics.html.
 
 If the available customisation isn't sufficient, then you can subclass the
 following :class:`colanderalchemy.SQLAlchemySchemaNode` methods when you need
 more control:
 
 * :meth:`SQLAlchemySchemaNode.get_schema_from_column`, which
-  returns a ``colander.SchemaNode`` given a ``sqlachemy.schema.Column``
+  returns a :class:`colander.SchemaNode` given a
+  :class:`sqlachemy.schema.Column`
 
 * :meth:`SQLAlchemySchemaNode.get_schema_from_relationship`,
-  which returns a ``colander.SchemaNode`` given a
-  ``sqlalchemy.orm.relationship``.
-  
+  which returns a :class:`colander.SchemaNode` given a
+  :meth:`sqlalchemy.orm.relationship`.
+
 
 .. _info_argument:
 
 Configuring within SQLAlchemy models
 ------------------------------------
 
-One of the most useful aspects of ``ColanderAlchemy`` is the ability to
+One of the most useful aspects of ColanderAlchemy is the ability to
 customize the schema being built by including hints directly in your
-``SQLAlchemy`` models. This means you can define just one ``SQLAlchemy``
-model and have it translate to a fully-customised ``Colander`` schema, and
+SQLAlchemy models. This means you can define just one SQLAlchemy
+model and have it translate to a fully-customised Colander schema, and
 do so purely using declarative code.  Alternatively, since the resulting schema
 is just a :class:`colander.SchemaNode`, you can configure it imperatively too,
 if you prefer.
 
-``Colander`` options can be specified declaratively in ``SQLAlchemy`` models
+Colander options can be specified declaratively in SQLAlchemy models
 using the ``info`` argument that you can pass to either
-:class:`sqlalchemy.Column` or :meth:`sqlalchemy.orm.relationship`.  ``info``
+:class:`sqlalchemy.Column` or :meth:`sqlalchemy.orm.relationship`. ``info``
 accepts any and all options that :class:`colander.SchemaNode` objects do and
 should be specified like so:
 
@@ -63,14 +64,14 @@ should be specified like so:
 
 and you can add any number of other options into the ``dict`` structure as
 described above.  So, anything you want passed to the resulting mapped
-:class`colander.SchemaNode` should be added here.  This also includes
-arbitrary attributes like ``widget``, which, whilst not part of ``Colander`` by
-default, is useful for a library like ``Deform``.
+:class:`colander.SchemaNode` should be added here.  This also includes
+arbitrary attributes like ``widget``, which, whilst not part of Colander by
+default, is useful for a library like Deform.
 
 Note that for a relationship, these configured attributes will only apply to
 the outer mapped :class:`colander.SchemaNode`; this *outer* node being a
 :class:`colander.Sequence` or :class:`colander.Mapping`, depending on whether
-the SQLAlchemy relationship is x-to-many or x-to-one, respectively. 
+the SQLAlchemy relationship is x-to-many or x-to-one, respectively.
 
 To customise the inner mapped class, use the special attribute
 ``__colanderalchemy_config__`` on the class itself and define this as a
@@ -136,10 +137,10 @@ A full worked example could be like this:
 Customizable Keyword Arguments
 ------------------------------
 
-``sqlalchemy.Column`` and ``sqlalchemy.orm.relationship`` can be configured
-with an ``info`` argument that ``ColanderAlchemy`` will use to customise
+:class:`sqlalchemy.Column` and :meth:`sqlalchemy.orm.relationship` can be configured
+with an ``info`` argument that ColanderAlchemy will use to customise
 resulting :class:`colander.SchemaNode` objects for each attribute.  The
-special (magic) key for attributes is ``colanderalchemy``, so a Column 
+special (magic) key for attributes is ``colanderalchemy``, so a ``Column``
 definition should look like how it was mentioned above in :ref:`info_argument`.
 
 This means you can customise options like:
@@ -156,25 +157,25 @@ This means you can customise options like:
     * ``widget``
 
 Keep in mind the above list isn't exhaustive and you should
-refer to the complete documentation at 
-http://docs.pylonsproject.org/projects/colander/en/latest/basics.html.
+refer to the complete list of constructor arguments in the `Colander
+API documentation for SchemaNode
+<http://docs.pylonsproject.org/projects/colander/en/latest/api.html#colander.SchemaNode>`_.
 
 So, as an example, the value of ``title`` will be passed as the keyword argument
-``title`` when instantiating the ``colander.SchemaNode``. For more information
-about what each of the options can do, see the `Colander
-<http://rtd.pylonsproject.org/projects/colander/>`_ documentation.
+``title`` when instantiating the :class:`colander.SchemaNode`. For more information
+about what each of the options can do, see the `Colander documentation
+<http://docs.pylonsproject.org/projects/colander/>`_.
 
 In addition, you can specify the following custom options to control
-what ``ColanderAlchemy`` itself does:
+what ColanderAlchemy itself does:
 
     * ``exclude`` - Boolean value for whether to exclude a given attribute.
       Extremely useful for keeping a ``Column`` or ``relationship`` out of
       a schema.  For instance, an internal field that shouldn't be made
-      available on a ``Deform`` form.
+      available on a Deform form.
     * ``children`` - An iterable (such as a list or tuple) of child nodes
       that should be used explicitly rather than mapping the current
       SQLAlchemy aspect.
     * ``name`` - Identifier for the resulting mapped Colander node.
     * ``typ`` - An explicitly-configured Colander node type.
 
-

docs/source/deform.rst

@@ -3,9 +3,11 @@
 Examples: using ColanderAlchemy with Deform
 ===========================================
 
-When using ``ColanderAlchemy``, the resulting ``Colander`` schema will
+When using ColanderAlchemy, the resulting Colander schema will
 reflect the configuration on the mapped class, as shown in the code below::
 
+.. code-block:: python
+
     from colanderalchemy import SQLAlchemySchemaNode
 
     from sqlalchemy import Enum, ForeignKey, Integer, Unicode
@@ -35,7 +37,9 @@ reflect the configuration on the mapped class, as shown in the code below::
     schema = SQLAlchemySchemaNode(Person)
 
 The resulting schema from the code above is the same as what would
-be produced by constructing the following ``Colander`` schema by hand::
+be produced by constructing the following Colander schema by hand::
+
+.. code-block:: python
 
     import colander
 
@@ -65,10 +69,12 @@ be produced by constructing the following ``Colander`` schema by hand::
     schema = Person()
 
 Note the various configuration aspects like field length and the like
-will automatically be mapped. This means that getting a ``Deform`` form
-to use ``ColanderAlchemy`` is as simple as using any other ``Colander``
+will automatically be mapped. This means that getting a Deform form
+to use ColanderAlchemy is as simple as using any other Colander
 schema::
 
+.. code-block:: python
+
     from colanderalchemy import SQLAlchemySchemaNode
     from deform import Form
 
@@ -77,13 +83,13 @@ schema::
 
     # Using ColanderAlchemy is easy!
     person = SQLAlchemySchemaNode(Person)
-    
+
     form = Form(person, buttons=('submit',))
 
 Keep in mind that if you want additional control over the resulting
-``Colander`` schema and nodes produced (such as controlling a node's `title`,
-`description`, `widget` or more), you are able to provide appropriate keyword
-arguments declaratively within the ``SQLAlchemy`` model as part of the
-respective ``info`` argument to a :class:`sqlalchemy.Column` or
-:meth:`sqlalchemy.orm.relationship` declaration. For more information, see
-:ref:`customization`.
+Colander schema and nodes produced (such as controlling a node's
+``title``, ``description``, ``widget`` or more), you are able to provide
+appropriate keyword arguments declaratively within the SQLAlchemy model
+as part of the respective ``info`` argument to a
+:class:`sqlalchemy.Column` or :meth:`sqlalchemy.orm.relationship`
+declaration. For more information, see :ref:`customization`.

docs/source/examples.rst

@@ -6,12 +6,14 @@ Examples
 Less boilerplate
 ----------------
 
-The best way to illustrate the benefit of using ``ColanderAlchemy`` is to
-show a comparison between the code required to represent ``SQLAlchemy``
-model as a ``Colander`` schema.
+The best way to illustrate the benefit of using ColanderAlchemy is to
+show a comparison between the code required to represent SQLAlchemy
+model as a Colander schema.
 
 Suppose you have these SQLAlchemy mapped classes::
 
+.. code-block:: python
+
     from sqlalchemy import Column, Enum, ForeignKey, Integer, Unicode
     from sqlalchemy.ext.declarative import declarative_base
     from sqlalchemy.orm import relationship
@@ -48,6 +50,8 @@ Suppose you have these SQLAlchemy mapped classes::
 
 The code you need to create the Colander schema for ``Person`` would be::
 
+.. code-block:: python
+
     import colander
 
 
@@ -95,17 +99,24 @@ The code you need to create the Colander schema for ``Person`` would be::
     person = Person()
 
 
-By contrast, all you need to obtain the same Colander schema for the ``Person`` mapped class using ``ColanderAlchemy`` is simply::
+By contrast, all you need to obtain the same Colander schema for the
+``Person`` mapped class using ColanderAlchemy is simply::
+
+.. code-block:: python
 
     from colanderalchemy import setup_schema
 
     setup_schema(None, Person)
     schema = Person.__colanderalchemy__
 
+
 Or alternatively, you may do this::
 
+.. code-block:: python
+
     from colanderalchemy import SQLAlchemySchemaNode
 
     schema = SQLAlchemySchemaNode(Person)
 
+
 As you can see, it's a lot simpler.

docs/source/index.rst

@@ -33,7 +33,7 @@ Now, once you configure any mapped class, you'll automatically get a mapped
 Colander schema on the class as the attribute ``__colanderalchemy__``.
 Keep in mind that you should configure the event listener as soon as possible
 in your application, especially if you're using `declarative
-<http://docs.sqlalchemy.org/latest/orm/extensions/declarative/>`_
+<http://docs.sqlalchemy.org/en/latest/orm/extensions/declarative/>`_
 definitions.
 
 By associating ``ColanderAlchemy`` configuration with your mapped class,