Improve documentation for functions applied to types other than Geome…

…try (#380)

doc/conf.py

@@ -91,6 +91,10 @@
 # A list of ignored prefixes for module index sorting.
 #modindex_common_prefix = []
 
+# -- Options for Autodoc ---------------------------------------------------
+autodoc_default_options = {
+    'exclude-members': 'inherit_cache'
+}
 
 # -- Options for HTML output ---------------------------------------------------
 

geoalchemy2/elements.py

@@ -244,6 +244,7 @@ class CompositeElement(FunctionElement):
     """Instances of this class wrap a Postgres composite type."""
 
     inherit_cache = False
+    """The cache is disabled for this class."""
 
     def __init__(self, base, field, type_):
         self.name = field

geoalchemy2/functions.py

@@ -45,6 +45,23 @@
 
       session.scalar(lake.geom.ST_Area())
 
+.. warning::
+
+    A few functions (like `ST_Transform()`, `ST_Union()`, `ST_SnapToGrid()`, ...) can be used on
+    several spatial types (:class:`geoalchemy2.types.Geometry`,
+    :class:`geoalchemy2.types.Geography` and / or :class:`geoalchemy2.types.Raster` types). In
+    GeoAlchemy2, these functions are only defined for the :class:`geoalchemy2.types.Geometry` type,
+    as it can not be defined for several types at the same time. Therefore, using these functions on
+    :class:`geoalchemy2.types.Geography` or :class:`geoalchemy2.types.Raster` requires minor
+    tweaking to enforce the type by passing the `type_=Geography` or `type_=Raster` argument to the
+    function::
+
+        s = select([func.ST_Transform(
+                            lake_table.c.raster,
+                            2154,
+                            type_=Raster)
+                        .label('transformed_raster')])
+
 Reference
 ---------
 
@@ -108,6 +125,7 @@ def _register_geo_function(cls, clsname, clsdict):
 class TableRowElement(ColumnElement):
 
     inherit_cache = False
+    """The cache is disabled for this class."""
 
     def __init__(self, selectable):
         self.selectable = selectable
@@ -123,6 +141,7 @@ class ST_AsGeoJSON(_GeoFunctionBase):
 
     name = "ST_AsGeoJSON"
     inherit_cache = True
+    """The cache is enabled for this class."""
 
     def __init__(self, *args, **kwargs):
         expr = kwargs.pop('expr', None)