Format docstrings

Author: tomalrussell

src/snail/damages.py

@@ -1,4 +1,5 @@
 """Damage assessment"""
+
 from abc import ABC
 import numpy
 import pandas
@@ -72,16 +73,16 @@ def from_csv(
 
         Parameters
         ----------
-        fname: str, path object or file-like object
-        intensity_col: str, default "intensity"
+        fname : str, path object or file-like object
+        intensity_col : str, default "intensity"
             Column name to read hazard intensity values
-        damage_col: str, default "damage_ratio"
+        damage_col : str, default "damage_ratio"
             Column name to read damage values
-        comment: str, default "#"
+        comment : str, default "#"
             Indicates remainder of the line in the CSV should not be parsed.
             If found at the beginning of a line, the line will be ignored
             altogether.
-        kwargs:
+        kwargs
             see pandas.read_csv documentation
 
         Returns
@@ -115,19 +116,19 @@ def from_excel(
 
         Parameters
         ----------
-        fname: str, path object or file-like object
-        sheet_name: str, int
+        fname : str, path object or file-like object
+        sheet_name : str or int
             Strings are used for sheet names. Integers are used in zero-indexed sheet
             positions (chart sheets do not count as a sheet position).
-        intensity_col: str, default "intensity"
+        intensity_col : str, default "intensity"
             Column name to read hazard intensity values
-        damage_col: str, default "damage_ratio"
+        damage_col : str, default "damage_ratio"
             Column name to read damage values
-        comment: str, default "#"
+        comment : str, default "#"
             Indicates remainder of the line in the CSV should not be parsed.
             If found at the beginning of a line, the line will be ignored
             altogether.
-        kwargs:
+        kwargs
             see pandas.read_csv documentation
 
         Returns
@@ -159,9 +160,9 @@ def interpolate(
 
         Parameters
         ----------
-        a: PiecewiseLinearDamageCurve
-        b: PiecewiseLinearDamageCurve
-        factor: float
+        a : PiecewiseLinearDamageCurve
+        b : PiecewiseLinearDamageCurve
+        factor : float
             Interpolation factor, used to calculate the new curve
 
         Returns
@@ -189,6 +190,7 @@ def damage_fraction(self, exposure: numpy.array) -> numpy.array:
         return self._interpolate(exposure)
 
     def translate_y(self, y: float):
+        """Translate damage by a factor, y"""
         damage = self.damage + y
 
         return PiecewiseLinearDamageCurve(
@@ -201,6 +203,7 @@ def translate_y(self, y: float):
         )
 
     def scale_y(self, y: float):
+        """Scale damage by a factor, y"""
         damage = self.damage * y
 
         return PiecewiseLinearDamageCurve(
@@ -213,6 +216,7 @@ def scale_y(self, y: float):
         )
 
     def translate_x(self, x: float):
+        """Translate intensity by a factor, x"""
         intensity = self.intensity + x
 
         return PiecewiseLinearDamageCurve(
@@ -225,6 +229,7 @@ def translate_x(self, x: float):
         )
 
     def scale_x(self, x: float):
+        """Scale intensity by a factor, x"""
         intensity = self.intensity * x
 
         return PiecewiseLinearDamageCurve(
@@ -238,6 +243,7 @@ def scale_x(self, x: float):
 
     @staticmethod
     def clip_curve_data(intensity, damage):
+        """Clip damage curve values to valid 0-1 damage range"""
         if (damage.max() > 1) or (damage.min() < 0):
             # WARNING clipping out-of-bounds damage fractions
             bounds = (
@@ -281,6 +287,7 @@ def clip_curve_data(intensity, damage):
         return intensity, damage
 
     def plot(self, ax=None):
+        """Plot a line chart of the damage curve"""
         import matplotlib.pyplot as plt
 
         if ax is None:

src/snail/intersection.py

@@ -45,20 +45,22 @@ class GridDefinition:
     output files. They effectively form the first two rows of a 3x3 matrix:
 
 
-    ```
-    | x |   | a  b  c | | i |
-    | y | = | d  e  f | | j |
-    | 1 |   | 0  0  1 | | 1 |
-    ```
+    .. code-block:: text
+
+        | x |   | a  b  c | | i |
+        | y | = | d  e  f | | j |
+        | 1 |   | 0  0  1 | | 1 |
+
 
     In cases without shear or rotation, `a` and `e` define scaling or grid cell
     size, while `c` and `f` define the offset or grid upper-left corner:
 
-    ```
-    | x_scale 0       x_offset |
-    | 0       y_scale y_offset |
-    | 0       0       1        |
-    ```
+    .. code-block:: text
+
+        | x_scale 0       x_offset |
+        | 0       y_scale y_offset |
+        | 0       0       1        |
+
     """
 
     crs: str
@@ -68,6 +70,7 @@ class GridDefinition:
 
     @classmethod
     def from_rasterio_dataset(cls, dataset):
+        """GridDefinition for a rasterio dataset"""
         crs = dataset.crs
         width = dataset.width
         height = dataset.height
@@ -77,6 +80,7 @@ def from_rasterio_dataset(cls, dataset):
 
     @classmethod
     def from_raster(cls, fname):
+        """GridDefinition for a raster file (readable by rasterio)"""
         with rasterio.open(fname) as dataset:
             grid = GridDefinition.from_rasterio_dataset(dataset)
         return grid
@@ -92,6 +96,7 @@ def from_extent(
         cell_height: float,
         crs,
     ):
+        """GridDefinition for a given extent, cell size and CRS"""
         return GridDefinition(
             crs=crs,
             width=math.ceil((xmax - xmin) / cell_width),
@@ -205,7 +210,8 @@ def split_polygons(
     return splits
 
 
-def generate_grid_boxes(grid):
+def generate_grid_boxes(grid: GridDefinition):
+    """Generate all the box polygons for a grid"""
     a, b, c, d, e, f = grid.transform
     idx = numpy.arange(grid.width * grid.height)
     i, j = numpy.unravel_index(idx, (grid.width, grid.height))