Improve doc formatting (#369)

doc/alembic.rst

@@ -215,66 +215,66 @@ columns in a SQLite database, the ``env.py`` file should look like the following
 
 .. code-block:: python
 
-from alembic.autogenerate import rewriter
-
-writer = rewriter.Rewriter()
-
-
-@writer.rewrites(ops.AddColumnOp)
-def add_geo_column(context, revision, op):
-"""This function replaces the default AddColumnOp by a geospatial-specific one."""
-    col_type = op.column.type
-    if isinstance(col_type, TypeDecorator):
-        dialect = context.bind().dialect
-        col_type = col_type.load_dialect_impl(dialect)
-    if isinstance(col_type, (Geometry, Geography, Raster)):
-        new_op = AddGeospatialColumn(op.table_name, op.column, op.schema)
-    else:
-        new_op = op
-    return new_op
-
-
-@writer.rewrites(ops.DropColumnOp)
-def drop_geo_column(context, revision, op):
-"""This function replaces the default DropColumnOp by a geospatial-specific one."""
-    col_type = op.to_column().type
-    if isinstance(col_type, TypeDecorator):
-        dialect = context.bind.dialect
-        col_type = col_type.load_dialect_impl(dialect)
-    if isinstance(col_type, (Geometry, Geography, Raster)):
-        new_op = DropGeospatialColumn(op.table_name, op.column_name, op.schema)
-    else:
-        new_op = op
-    return new_op
-
-
-def load_spatialite(dbapi_conn, connection_record):
-    """Load SpatiaLite extension in SQLite DB."""
-    dbapi_conn.enable_load_extension(True)
-    dbapi_conn.load_extension(os.environ['SPATIALITE_LIBRARY_PATH'])
-    dbapi_conn.enable_load_extension(False)
-    dbapi_conn.execute('SELECT InitSpatialMetaData()')
-
-
-def run_migrations_offline():
-    # ...
-    context.configure(
-        # ...
-        process_revision_directives=writer,
-    )
-    # ...
+    from alembic.autogenerate import rewriter
+
+    writer = rewriter.Rewriter()
+
+
+    @writer.rewrites(ops.AddColumnOp)
+    def add_geo_column(context, revision, op):
+    """This function replaces the default AddColumnOp by a geospatial-specific one."""
+        col_type = op.column.type
+        if isinstance(col_type, TypeDecorator):
+            dialect = context.bind().dialect
+            col_type = col_type.load_dialect_impl(dialect)
+        if isinstance(col_type, (Geometry, Geography, Raster)):
+            new_op = AddGeospatialColumn(op.table_name, op.column, op.schema)
+        else:
+            new_op = op
+        return new_op
+
+
+    @writer.rewrites(ops.DropColumnOp)
+    def drop_geo_column(context, revision, op):
+    """This function replaces the default DropColumnOp by a geospatial-specific one."""
+        col_type = op.to_column().type
+        if isinstance(col_type, TypeDecorator):
+            dialect = context.bind.dialect
+            col_type = col_type.load_dialect_impl(dialect)
+        if isinstance(col_type, (Geometry, Geography, Raster)):
+            new_op = DropGeospatialColumn(op.table_name, op.column_name, op.schema)
+        else:
+            new_op = op
+        return new_op
+
+
+    def load_spatialite(dbapi_conn, connection_record):
+        """Load SpatiaLite extension in SQLite DB."""
+        dbapi_conn.enable_load_extension(True)
+        dbapi_conn.load_extension(os.environ['SPATIALITE_LIBRARY_PATH'])
+        dbapi_conn.enable_load_extension(False)
+        dbapi_conn.execute('SELECT InitSpatialMetaData()')
 
 
-def run_migrations_online():
-    # ...
-    if connectable.dialect.name == "sqlite":
-        # Load the SpatiaLite extension when the engine connects to the DB
-        listen(connectable, 'connect', load_spatialite)
-
-    with connectable.connect() as connection:
+    def run_migrations_offline():
         # ...
         context.configure(
             # ...
             process_revision_directives=writer,
         )
         # ...
+
+
+    def run_migrations_online():
+        # ...
+        if connectable.dialect.name == "sqlite":
+            # Load the SpatiaLite extension when the engine connects to the DB
+            listen(connectable, 'connect', load_spatialite)
+
+        with connectable.connect() as connection:
+            # ...
+            context.configure(
+                # ...
+                process_revision_directives=writer,
+            )
+            # ...

doc/conf.py

@@ -27,7 +27,12 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx_gallery.gen_gallery']
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.viewcode',
+    'sphinx_gallery.gen_gallery',
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

doc/elements.rst

@@ -3,6 +3,16 @@
 Elements
 ========
 
+.. autoclass:: geoalchemy2.elements.HasFunction
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: geoalchemy2.elements._SpatialElement
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 .. autoclass:: geoalchemy2.elements.WKTElement
    :members:
    :undoc-members:
@@ -16,3 +26,7 @@ Elements
 .. autoclass:: geoalchemy2.elements.RasterElement
    :members:
    :show-inheritance:
+
+.. autoclass:: geoalchemy2.elements.CompositeElement
+   :members:
+   :show-inheritance:

geoalchemy2/alembic_helpers.py

@@ -88,8 +88,8 @@ def reverse(self):
 def add_geospatial_column(operations, operation):
     """Handle the actual column addition according to the dialect backend.
 
-    Parameters:
-        operations: Operations object from alembic base, defining high level migration operations
+    Args:
+        operations: Operations object from alembic base, defining high level migration operations.
         operation: AddGeospatialColumn call, with attributes for table_name, column_name,
             column_type, and optional keywords.
     """
@@ -125,9 +125,12 @@ def add_geospatial_column(operations, operation):
 
 @Operations.implementation_for(DropGeospatialColumn)
 def drop_geospatial_column(operations, operation):
-    """
-    Handles the actual column removal by checking for the dialect backend and issuing proper
-    commands.
+    """Handle the actual column removal according to the dialect backend.
+
+    Args:
+        operations: Operations object from alembic base, defining high level migration operations.
+        operation: AddGeospatialColumn call, with attributes for table_name, column_name,
+            column_type, and optional keywords.
     """
 
     table_name = operation.table_name

geoalchemy2/elements.py

@@ -19,28 +19,20 @@
 
 
 class HasFunction(object):
+    """Base class used as a marker to know if a given element has a 'geom_from' function."""
     pass
 
 
 class _SpatialElement(HasFunction):
-    """
-    The base class for :class:`geoalchemy2.elements.WKTElement` and
-    :class:`geoalchemy2.elements.WKBElement`.
-
-    The first argument passed to the constructor is the data wrapped
-    by the ``_SpatialElement` object being constructed.
-
-    Additional arguments:
-
-    ``srid``
+    """The base class for public spatial elements.
 
-        An integer representing the spatial reference system. E.g. 4326.
-        Default value is -1, which means no/unknown reference system.
-
-    ``extended``
-
-        A boolean indicating whether the extended format (EWKT or EWKB)
-        is used. Default is ``False``.
+    Args:
+        data: The first argument passed to the constructor is the data wrapped
+            by the ``_SpatialElement`` object being constructed.
+        srid: An integer representing the spatial reference system. E.g. ``4326``.
+            Default value is ``-1``, which means no/unknown reference system.
+        extended: A boolean indicating whether the extended format (EWKT or EWKB)
+            is used. Default is ``False``.
 
     """
 
@@ -249,9 +241,7 @@ def _data_from_desc(desc):
 
 
 class CompositeElement(FunctionElement):
-    """
-    Instances of this class wrap a Postgres composite type.
-    """
+    """Instances of this class wrap a Postgres composite type."""
 
     inherit_cache = False
 

geoalchemy2/exc.py

@@ -1,12 +1,9 @@
-""" Exceptions used with GeoAlchemy2.
-"""
+"""Exceptions used with GeoAlchemy2."""
 
 
 class GeoAlchemyError(Exception):
-    """ Generic error class. """
+    """Generic error class."""
 
 
 class ArgumentError(GeoAlchemyError):
-    """ Raised when an invalid or conflicting function argument is
-    supplied.
-    """
+    """Raised when an invalid or conflicting function argument is supplied."""

geoalchemy2/functions.py

@@ -289,13 +289,14 @@ def _compile_sqlite(element, compiler, **kw):
 def register_sqlite_mapping(mapping):
     """Register compilation mappings for the given functions.
 
-    ``mapping`` should have the following form::
-
-        {
-            "function_name_1": "sqlite_function_name_1",
-            "function_name_2": "sqlite_function_name_2",
-            ...
-        }
+    Args:
+        mapping: Should have the following form::
+
+                {
+                    "function_name_1": "sqlite_function_name_1",
+                    "function_name_2": "sqlite_function_name_2",
+                    ...
+                }
     """
     for cls, fn in mapping.items():
         _compiles_default(cls)

geoalchemy2/shape.py

@@ -24,18 +24,17 @@ def dumps(ob, hex=False, srid=None, **kw):
         """Dump a WKB representation of a geometry to a byte string, or a
         hex-encoded string if ``hex=True``.
 
-        Parameters
-        ----------
-        ob : geometry
-            The geometry to export to well-known binary (WKB) representation
-        hex : bool
-            If true, export the WKB as a hexadecimal string. The default is to
-            return a binary string/bytes object.
-        srid : int
-            Spatial reference system ID to include in the output. The default
-            value means no SRID is included.
-        **kw : kwargs
-            See available keyword output settings in ``shapely.geos.WKBWriter``.
+        Args:
+            ob (geometry):
+                The geometry to export to well-known binary (WKB) representation
+            hex (bool):
+                If true, export the WKB as a hexadecimal string. The default is to
+                return a binary string/bytes object.
+            srid (int):
+                Spatial reference system ID to include in the output. The default
+                value means no SRID is included.
+        Keyword args:
+            kwargs: See available keyword output settings in ``shapely.geos.WKBWriter``.
         """
         if srid is not None:
             # clone the object and set the SRID before dumping
@@ -58,6 +57,9 @@ def to_shape(element):
     Function to convert a :class:`geoalchemy2.types.SpatialElement`
     to a Shapely geometry.
 
+    Args:
+        element: The element to convert into a ``Shapely`` object.
+
     Example::
 
         lake = Session.query(Lake).get(1)
@@ -80,17 +82,13 @@ def from_shape(shape, srid=-1, extended=False):
     Function to convert a Shapely geometry to a
     :class:`geoalchemy2.types.WKBElement`.
 
-    Additional arguments:
-
-    ``srid``
-
-        An integer representing the spatial reference system. E.g. 4326.
-        Default value is -1, which means no/unknown reference system.
-
-    ``extended``
-
-        A boolean to switch between WKB and EWKB.
-        Default value is False.
+    Args:
+        srid:
+            An integer representing the spatial reference system. E.g. ``4326``.
+            Default value is ``-1``, which means no/unknown reference system.
+        extended:
+            A boolean to switch between WKB and EWKB.
+            Default value is False.
 
     Example::