Tweak docs, define __init__ for all classes

.github/workflows/docs.yml

@@ -22,7 +22,7 @@ jobs:
 
       - run: pip install -e ".[docs]"
       # We use a custom build script for pdoc itself, ideally you just run `pdoc -o docs/ ...` here.
-      - run: pdoc -o docs/ ribasim
+      - run: pdoc -o docs/ ribasim --docformat numpy
 
       - uses: actions/upload-pages-artifact@v1
         with:

ribasim/basin.py

@@ -1,5 +1,6 @@
 from typing import Optional
 
+import pandas as pd
 import pandera as pa
 from pandera.typing import DataFrame, Series
 from pydantic import BaseModel
@@ -46,31 +47,57 @@ class Basin(InputMixin, BaseModel):
     Input for a (sub-)basin: an area of land where all flowing surface water
     converges to a single point.
 
-    A basin is defined by a tabulation of:
+    Parameters
+    ----------
+    profile: pandas.DataFrame
 
-    * storage
-    * area
-    * water level
+        A tabulation with the columns:
 
-    This data is provided by the ``profile`` DataFrame.
+        * storage
+        * area
+        * water level
 
-    In Ribasim, the basin receives water balance terms such as:
+    static: pandas.DataFrame, optional
 
-    * potential evaporation
-    * precipitation
-    * groundwater drainage
-    * groundwater infiltration
-    * urban runoff
+        Static forcing with columns:
 
-    This may be set in the ``static`` dataframe for constant data, or ``forcing``
-    for time varying data.
+        * potential evaporation
+        * precipitation
+        * groundwater drainage
+        * groundwater infiltration
+        * urban runoff
+
+    forcing: pandas.DataFrame, optional
+
+        Time varying forcing with columns:
+
+        * time
+        * potential evaporation
+        * precipitation
+        * groundwater drainage
+        * groundwater infiltration
+        * urban runoff
+
+    state: pandas.DataFrame, optional
+
+        Initial state with columns:
+
+        * storage
+        * concentration
 
-    A basin may be initialized with an initial state for storage or
-    concentration. This is set in the ``state`` dataframe.
     """
 
     _input_type = "Basin"
     profile: DataFrame[ProfileSchema]
     static: Optional[DataFrame[StaticSchema]] = None
     forcing: Optional[DataFrame[ForcingSchema]] = None
     state: Optional[DataFrame[StateSchema]] = None
+
+    def __init__(
+        self,
+        profile: pd.DataFrame,
+        static: Optional[pd.DataFrame] = None,
+        forcing: Optional[pd.DataFrame] = None,
+        state: Optional[pd.DataFrame] = None,
+    ):
+        super().__init__(**locals())

ribasim/edge.py

@@ -15,5 +15,20 @@ class StaticSchema(pa.SchemaModel):
 
 
 class Edge(InputMixin, BaseModel):
+    """
+    Defines the connections between nodes.
+
+    Parameters
+    ----------
+    static: pandas.DataFrame
+
+        With columns:
+
+        * from_node_id
+        * to_node_id
+        * geometry
+
+    """
+
     _input_type = "Edge"
     static: DataFrame[StaticSchema]

ribasim/fractional_flow.py

@@ -1,5 +1,6 @@
 from typing import Optional
 
+import pandas as pd
 import pandera as pa
 from pandera.typing import DataFrame, Series
 from pydantic import BaseModel
@@ -21,6 +22,32 @@ class ForcingSchema(pa.SchemaModel):
 
 
 class FractionalFlow(InputMixin, BaseModel):
+    """
+    Receives a fraction of the flow. The fractions must sum to 1.0 for a
+    furcation.
+
+    Parameters
+    ----------
+    static: pandas.DataFrame
+
+        With columns:
+
+        * node_id
+        * fraction
+
+    forcing: pandas.DataFrame, optional
+
+        With columns:
+
+        * node_id
+        * time
+        * fraction
+
+    """
+
     _input_type = "FractionalFlow"
     static: DataFrame[StaticSchema]
     forcing: Optional[DataFrame[ForcingSchema]] = None
+
+    def __init__(self, static: pd.DataFrame, forcing: Optional[pd.DataFrame]):
+        super().__init__(**locals())

ribasim/input_base.py

@@ -11,7 +11,7 @@
 
 T = TypeVar("T")
 
-__all__ = ()
+__all__ = ("InputMixin",)
 
 
 class InputMixin(abc.ABC):

ribasim/level_control.py

@@ -1,3 +1,4 @@
+import pandas as pd
 import pandera as pa
 from pandera.typing import DataFrame, Series
 from pydantic import BaseModel
@@ -13,5 +14,22 @@ class StaticSchema(pa.SchemaModel):
 
 
 class LevelControl(InputMixin, BaseModel):
+    """
+    Controls the level in a basin.
+
+    Parameters
+    ----------
+    static: pandas.DataFrame
+
+        With columns:
+
+        * node_id
+        * target_level
+
+    """
+
     _input_type = "LevelControl"
     static: DataFrame[StaticSchema]
+
+    def __init__(self, static: pd.DataFrame):
+        super().__init__(**locals())

ribasim/linear_level_connection.py

@@ -1,3 +1,4 @@
+import pandas as pd
 import pandera as pa
 from pandera.typing import DataFrame, Series
 from pydantic import BaseModel
@@ -13,5 +14,23 @@ class StaticSchema(pa.SchemaModel):
 
 
 class LinearLevelConnection(InputMixin, BaseModel):
+    """
+    Flow through this connection linearly depends on the level difference
+    between the two connected basins.
+
+    Parameters
+    ----------
+    static: pd.DataFrame
+
+        With columns:
+
+        * node_id
+        * conductance
+
+    """
+
     _input_type = "LinearLevelConnection"
     static: DataFrame[StaticSchema]
+
+    def __init__(self, static: pd.DataFrame):
+        super().__init__(**locals())

ribasim/model.py

@@ -1,6 +1,6 @@
 import datetime
 from pathlib import Path
-from typing import Optional
+from typing import Optional, Union
 
 import tomli
 import tomli_w
@@ -31,6 +31,24 @@
 
 
 class Model(BaseModel):
+    """
+    Ribasim model containing the location of the nodes, the edges between the
+    nodes, and the node parametrization.
+
+    Parameters
+    ----------
+    modelname: str
+    node: Node
+    edge: Edge
+    basin: Basin
+    fractional_flow: Optional[FractionalFlow]
+    level_control: Optional[LevelControl]
+    linear_level_connection: Optional[LinearLevelConnection]
+    tabulated_rating_curve: Optional[TabulatedRatingCurve]
+    starttime: Union[str, datetime.datetime]
+    endtime: Union[str, datetime.datetime]
+    """
+
     modelname: str
     node: Node
     edge: Edge
@@ -42,6 +60,21 @@ class Model(BaseModel):
     starttime: datetime.datetime
     endtime: datetime.datetime
 
+    def __init__(
+        self,
+        modelname: str,
+        starttime: Union[str, datetime.datetime],
+        endtime: Union[str, datetime.datetime],
+        node: Node,
+        edge: Edge,
+        basin: Basin,
+        fractional_flow: Optional[FractionalFlow] = None,
+        level_control: Optional[LevelControl] = None,
+        linear_level_connection: Optional[LinearLevelConnection] = None,
+        tabulated_rating_curve: Optional[TabulatedRatingCurve] = None,
+    ):
+        super().__init__(**locals())
+
     @classmethod
     def fields(cls):
         """Returns the names of the fields contained in the Model."""

ribasim/node.py

@@ -1,3 +1,4 @@
+import pandas as pd
 import pandera as pa
 from pandera.typing import DataFrame, Series
 from pandera.typing.geopandas import GeoSeries
@@ -14,5 +15,22 @@ class StaticSchema(pa.SchemaModel):
 
 
 class Node(InputMixin, BaseModel):
+    """
+    The Ribasim nodes as Point geometries.
+
+    Parameters
+    ----------
+    static: geopandas.GeoDataFrame
+
+        With columns:
+
+        * type
+        * geometry
+
+    """
+
     _input_type = "Node"
     static: DataFrame[StaticSchema]
+
+    def __init__(self, static: pd.DataFrame):
+        super().__init__(**locals())

ribasim/tabulated_rating_curve.py

@@ -1,3 +1,4 @@
+import pandas as pd
 import pandera as pa
 from pandera.typing import DataFrame, Series
 from pydantic import BaseModel
@@ -14,5 +15,24 @@ class StaticSchema(pa.SchemaModel):
 
 
 class TabulatedRatingCurve(InputMixin, BaseModel):
+    """
+    Linearly interpolates discharge between a tabulation of storage and
+    discharge.
+
+    Parameters
+    ----------
+    static: pd.DataFrame
+
+        Tabulation with columns:
+
+        * node_id
+        * storage
+        * discharge
+
+    """
+
     _input_type = "TabulatedRatingCurve"
     static: DataFrame[StaticSchema]
+
+    def __init__(self, static: pd.DataFrame):
+        super().__init__(**locals())