improve API docs (#217)

Fix #216. The rest of the docstrings still need some more treatment to follow numpydoc better. https://numpydoc.readthedocs.io/en/latest/example.html https://machow.github.io/quartodoc/get-started/docstring-examples.html ``` python -m numpydoc --validate ribasim.model.Model ```
Deltares · May 16, 2023 · 064c3ce · 064c3ce
1 parent c2ecbf1
commit 064c3ce
Show file tree

Hide file tree

Showing 14 changed files with 88 additions and 166 deletions.
diff --git a/docs/_quarto.yml b/docs/_quarto.yml
@@ -65,10 +65,6 @@ quartodoc:
       desc: The Model class represents an entire Ribasim model.
       contents:
         - Model
-        - Model.write
-        - Model.from_toml
-        - Model.plot
-
     - title: Network
       desc: The Node and Edge GeoPackage layers define the network layout.
       contents:
@@ -78,10 +74,13 @@ quartodoc:
       desc: Available node types to model different situations.
       contents:
         - Basin
-        - TabulatedRatingCurve
-        - LinearResistance
         - FractionalFlow
+        - LevelBoundary
         - LevelControl
+        - LinearResistance
+        - ManningResistance
+        - Pump
+        - TabulatedRatingCurve
     - title: Utility functions
       desc: Collection of utility functions.
       contents:

diff --git a/python/ribasim/ribasim/basin.py b/python/ribasim/ribasim/basin.py
@@ -46,46 +46,14 @@ class Basin(InputMixin, BaseModel):
 
     Parameters
     ----------
-    profile: pandas.DataFrame
-
-        A tabulation with the columns:
-
-        * node_id
-        * storage
-        * area
-        * water level
-
-    static: pandas.DataFrame, optional
-
-        Static forcing with columns:
-
-        * node_id
-        * potential evaporation
-        * precipitation
-        * groundwater drainage
-        * groundwater infiltration
-        * urban runoff
-
-    forcing: pandas.DataFrame, optional
-
-        Time varying forcing with columns:
-
-        * node_id
-        * time
-        * potential evaporation
-        * precipitation
-        * groundwater drainage
-        * groundwater infiltration
-        * urban runoff
-
-    state: pandas.DataFrame, optional
-
-        Initial state with columns:
-
-        * node_id
-        * storage
-        * concentration
-
+    profile : pandas.DataFrame
+        Table describing the geometry.
+    static : pandas.DataFrame, optional
+        Table describing the constant fluxes.
+    forcing : pandas.DataFrame, optional
+        Table describing the time-varying fluxes.
+    state : pandas.DataFrame, optional
+        Table describing the initial condition.
     """
 
     _input_type = "Basin"

diff --git a/python/ribasim/ribasim/edge.py b/python/ribasim/ribasim/edge.py
@@ -30,14 +30,8 @@ class Edge(InputMixin, BaseModel):
 
     Parameters
     ----------
-    static: pandas.DataFrame
-
-        With columns:
-
-        * from_node_id
-        * to_node_id
-        * geometry
-
+    static : pandas.DataFrame
+        Table describing the flow connections.
     """
 
     _input_type = "Edge"
@@ -59,8 +53,8 @@ def write(self, directory: FilePath, modelname: str) -> None:
 
         Parameters
         ----------
-        directory: FilePath
-        modelname: str
+        directory : FilePath
+        modelname : str
         """
         self.sort()
         directory = Path(directory)

diff --git a/python/ribasim/ribasim/fractional_flow.py b/python/ribasim/ribasim/fractional_flow.py
@@ -18,26 +18,12 @@ class Config:
 
 class FractionalFlow(InputMixin, BaseModel):
     """
-    Receives a fraction of the flow. The fractions must sum to 1.0 for a
-    furcation.
+    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
-
+    static : pandas.DataFrame
+        Table with the constant flow fractions.
     """
 
     _input_type = "FractionalFlow"

diff --git a/python/ribasim/ribasim/input_base.py b/python/ribasim/ribasim/input_base.py
@@ -78,8 +78,10 @@ def write(self, directory: FilePath, modelname: str) -> None:
 
         Parameters
         ----------
-        directory: FilePath
-        modelname: str
+        directory : FilePath
+            Path to the directory where to write the files.
+        modelname : str
+            Name of the model, used as a file name.
         """
         self.sort()
         directory = Path(directory)
@@ -128,8 +130,8 @@ def from_geopackage(cls: Type[T], path: FilePath) -> T:
 
         Parameters
         ----------
-        path: Path
-            Path to the GeoPackage
+        path : Path
+            Path to the GeoPackage.
 
         Returns
         -------
@@ -150,7 +152,7 @@ def from_config(cls: Type[T], config: Dict[str, Any]) -> T:
 
         Parameters
         ----------
-        config: Dict[str, Any]
+        config : Dict[str, Any]
 
         Returns
         -------

diff --git a/python/ribasim/ribasim/level_boundary.py b/python/ribasim/ribasim/level_boundary.py
@@ -19,12 +19,8 @@ class LevelBoundary(InputMixin, BaseModel):
 
     Parameters
     ----------
-    static: pandas.DataFrame
-
-        With columns:
-
-        * node_id
-        * level
+    static : pandas.DataFrame
+        Table with the constant water levels.
     """
 
     _input_type = "LevelBoundary"

diff --git a/python/ribasim/ribasim/level_control.py b/python/ribasim/ribasim/level_control.py
@@ -22,14 +22,8 @@ class LevelControl(InputMixin, BaseModel):
 
     Parameters
     ----------
-    static: pandas.DataFrame
-
-        With columns:
-
-        * node_id
-        * target_level
-        * resistance
-
+    static : pandas.DataFrame
+        Table with the constant target levels and resistances.
     """
 
     _input_type = "LevelControl"

diff --git a/python/ribasim/ribasim/linear_resistance.py b/python/ribasim/ribasim/linear_resistance.py
@@ -23,13 +23,8 @@ class LinearResistance(InputMixin, BaseModel):
 
     Parameters
     ----------
-    static: pd.DataFrame
-
-        With columns:
-
-        * node_id
-        * resistance
-
+    static : pd.DataFrame
+        Table with the constant resistances.
     """
 
     _input_type = "LinearResistance"

diff --git a/python/ribasim/ribasim/manning_resistance.py b/python/ribasim/ribasim/manning_resistance.py
@@ -23,16 +23,8 @@ class ManningResistance(InputMixin, BaseModel):
 
     Parameters
     ----------
-    static: pd.DataFrame
-
-        With columns:
-
-        * node_id
-        * length
-        * manning_n
-        * profile_width
-        * profile_slope
-
+    static : pd.DataFrame
+        Table with the constant Manning parameters.
     """
 
     _input_type = "ManningResistance"

diff --git a/python/ribasim/ribasim/model.py b/python/ribasim/ribasim/model.py
@@ -49,23 +49,41 @@ class Solver(BaseModel):
 
 class Model(BaseModel):
     """
+    A full Ribasim model schematisation with all input.
+
     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]
-    level_boundary: Optional[LevelBoundary]
+    modelname : str
+        Model name, used in TOML and GeoPackage file name.
+    node : Node
+        The ID, type and geometry of each node.
+    edge : Edge
+        How the nodes are connected.
+    basin : Basin
+        The waterbodies.
+    fractional_flow : Optional[FractionalFlow]
+        Split flows into fractions.
+    level_control : Optional[LevelControl]
+        Control the water level with a resistance.
+    level_boundary : Optional[LevelBoundary]
+        Boundary condition specifying the water level.
     linear_resistance: Optional[LinearResistance]
-    tabulated_rating_curve: Optional[TabulatedRatingCurve]
-    starttime: Union[str, datetime.datetime]
-    endtime: Union[str, datetime.datetime]
-    solver: Optional[Solver]
+        Linear flow resistance.
+    manning_resistance : Optional[ManningResistance]
+        Flow resistance based on the Manning formula.
+    tabulated_rating_curve : Optional[TabulatedRatingCurve]
+        Tabulated rating curve describing flow based on the upstream water level.
+    pump : Optional[Pump]
+        Prescribed flow rate from one basin to the other.
+    starttime : Union[str, datetime.datetime]
+        Starting time of the simulation.
+    endtime : Union[str, datetime.datetime]
+        End time of the simulation.
+    solver : Optional[Solver]
+        Solver settings.
     """
 
     modelname: str
@@ -161,12 +179,12 @@ def from_toml(path: FilePath) -> "Model":
 
         Parameters
         ----------
-        path: FilePath
+        path : FilePath
             Path to the configuration TOML file.
 
         Returns
         -------
-        model: Model
+        model : Model
         """
         path = Path(path)
         with open(path, "rb") as f:
@@ -189,12 +207,12 @@ def plot(self, ax=None) -> Any:
 
         Parameters
         ----------
-        ax: matplotlib.pyplot.Artist, optional
-            axes on which to draw the plot
+        ax : matplotlib.pyplot.Artist, optional
+            Axes on which to draw the plot.
 
         Returns
         -------
-        ax: matplotlib.pyplot.Artist
+        ax : matplotlib.pyplot.Artist
         """
         if ax is None:
             _, ax = plt.subplots()

diff --git a/python/ribasim/ribasim/node.py b/python/ribasim/ribasim/node.py
@@ -40,13 +40,8 @@ class Node(InputMixin, BaseModel):
 
     Parameters
     ----------
-    static: geopandas.GeoDataFrame
-
-        With columns:
-
-        * type
-        * geometry
-
+    static : geopandas.GeoDataFrame
+        Table with node ID, type and geometry.
     """
 
     _input_type = "Node"
@@ -72,8 +67,8 @@ def write(self, directory: FilePath, modelname: str) -> None:
 
         Parameters
         ----------
-        directory: FilePath
-        modelname: str
+        directory : FilePath
+        modelname : str
         """
         self.sort()
         directory = Path(directory)
@@ -106,7 +101,7 @@ def plot(self, **kwargs) -> Any:
 
         Parameters
         ----------
-        **kwargs: optional
+        **kwargs : optional
             Keyword arguments forwarded to GeoDataFrame.plot.
 
         Returns

diff --git a/python/ribasim/ribasim/pump.py b/python/ribasim/ribasim/pump.py
@@ -26,13 +26,8 @@ class Pump(InputMixin, BaseModel):
 
     Parameters
     ----------
-    static: pd.DataFrame
-
-        With columns:
-
-        * node_id
-        * flow_rate
-
+    static : pd.DataFrame
+        Table with constant flow rates.
     """
 
     _input_type = "Pump"