Added documentation for geoa module

doc/changelog.rst

 Changelog
 =========
 
+1.1 (dev)
+---------
+
+Highlights:
+
+* Added the ``geoa`` contrib module, for working with `geoalchemy2`_
+
+.. _geoalchemy2: http://geoalchemy-2.readthedocs.org/
+
 1.0.8
 -----
 

doc/db.rst

@@ -2,27 +2,34 @@ Database backends
 =================
 
 The purpose of Flask-Admin is to help you manage your data. For this, it needs some database backend in order to be
-able to access that data in the first place. At present, there are four different backends for you to choose
+able to access that data in the first place. At present, there are five different backends for you to choose
 from, depending on which database you would like to use for your application.
 
 .. toctree::
    :maxdepth: 2
 
    db_sqla
+   db_geoa
    db_mongoengine
    db_peewee
    db_pymongo
 
 If you don't know where to start, but you're familiar with relational databases, then you should probably look at using
-`SQLAlchemy <http://www.sqlalchemy.org/>`_. It is a full-featured toolkit, with support for SQLite, PostgreSQL, MySQL,
+`SQLAlchemy`_. It is a full-featured toolkit, with support for SQLite, PostgreSQL, MySQL,
 Oracle and MS-SQL amongst others. It really comes into its own once you have lots of data, and a fair amount of
-relations between your data models.
+relations between your data models. If you want to track spatial data like latitude/longitude
+points, you should look into `GeoAlchemy`_, as well.
 
 If you're looking for something simpler, or your data models are reasonably self-contained, then
-`MongoEngine <http://mongoengine.org/>`_ could be a better option. It is a python wrapper around the popular
-*NoSQL* database called `MongoDB <http://www.mongodb.org/>`_.
+`MongoEngine`_ could be a better option. It is a python wrapper around the popular
+*NoSQL* database called `MongoDB`_.
 
 Of course, if you feel that there's an awesome database wrapper that is missing from the list above, we'd greatly
 appreciate it if you could write the plugin for it and submit it as a pull request. A special section of these docs
 are dedicated to helping you through this process. See :doc:`model_guidelines`.
 
+.. _SQLAlchemy: http://www.sqlalchemy.org/
+.. _GeoAlchemy: http://geoalchemy-2.readthedocs.org/
+.. _MongoEngine: http://mongoengine.org/
+.. _MongoDB: http://www.mongodb.org/
+

doc/db_geoa.rst

+GeoAlchemy backend
+==================
+
+If you want to store spatial information in a GIS database, Flask-Admin has
+you covered. The `GeoAlchemy`_ backend extends the SQLAlchemy backend (just as
+GeoAlchemy extends SQLAlchemy) to give you a pretty and functional map-based
+editor for your admin pages.
+
+Notable features:
+
+ - Uses the amazing `Leaflet`_ Javascript library for displaying maps,
+   with map data from `Mapbox`_
+ - Uses `Leaflet.Draw`_ for editing geographic information interactively,
+   including points, lines, and polygons
+ - Graceful fallback to editing `GeoJSON`_ data in a ``<textarea>``, if the
+   user has turned off Javascript
+ - Works with a `Geometry`_ SQL field that is integrated with `Shapely`_ objects
+
+Getting Started
+---------------
+
+GeoAlchemy is based on SQLAlchemy, so you'll need to complete the "getting started"
+directions for SQLAlchemy backend first. For GeoAlchemy, you'll also need a
+map ID from `Mapbox`_, a map tile provider. (Don't worry, their basic plan
+is free, and works quite well.) Then, just include the map ID in your application
+settings::
+
+    app = Flask(__name__)
+    app.config['MAPBOX_MAP_ID'] = "example.abc123"
+
+.. note::
+  Leaflet supports loading map tiles from any arbitrary map tile provider, but
+  at the moment, Flask-Admin only supports Mapbox. If you want to use other
+  providers, make a pull request!
+
+Creating simple model
+---------------------
+
+GeoAlchemy comes with a `Geometry`_ field that is carefully divorced from the
+`Shapely`_ library. Flask-Admin takes the approach that if you're using spatial
+objects in your database, and you want an admin interface to edit those objects,
+you're probably already using Shapely, so we provide a Geometry field that is
+integrated with Shapely objects. To make your admin interface works, be sure to
+use this field rather that the one that ships with GeoAlchemy when defining your
+models::
+
+    from flask.ext.admin.contrib.geoa.sqltypes import Geometry
+
+    # .. flask initialization
+    db = SQLAlchemy(app)
+
+    class Location(db.Model):
+        id = db.Column(db.Integer, primary_key=True)
+        name = db.Column(db.String(64), unique=True)
+        point = db.Column(Geometry("POINT"))
+
+    if __name__ == '__main__':
+        admin = Admin(app)
+        admin.add_view(ModelView(User, db.session))
+
+        db.create_all()
+        app.run('0.0.0.0', 8000)
+
+Limitations
+-----------
+
+There's currently no way to sort, filter, or search on geometric fields
+in the admin. It's not clear that there's a good way to do so.
+If you have any ideas or suggestions, make a pull request!
+
+.. _GeoAlchemy: http://geoalchemy-2.readthedocs.org/
+.. _Leaflet: http://leafletjs.com/
+.. _Leaflet.Draw: https://github.com/Leaflet/Leaflet.draw
+.. _Shapely: http://toblerity.org/shapely/
+.. _Mapbox: https://www.mapbox.com/
+.. _GeoJSON: http://geojson.org/
+.. _Geometry: http://geoalchemy-2.readthedocs.org/en/latest/types.html#geoalchemy2.types.Geometry