Update the documentation-style names of all models of the HydPy-SW1D …

…model family as defined in issue #99.

hydpy/docs/rst/HydPy-SW1D.rst

@@ -4,7 +4,7 @@
 HydPy-SW1D (Shallow Water 1D)
 =============================
 
-All models of the `HydPy-SW1D` model family serve to solve the 1-dimensional shallow
+All models of the HydPy-SW1D model family serve to solve the 1-dimensional shallow
 water equations.  Opposed to models like |musk_mct|, they do so in a more
 `hydrodynamical` manner, which extends their scope to situations where traditional
 `hydrological` flood routing approaches fail.  Most importantly, they can account for
@@ -31,25 +31,19 @@ interface), for calculating the flow between channel segments (like |sw1d_lias|,
 follows the |RoutingModel_V2| interface), and for removing water from the lower
 segments (like |sw1d_weir_out|, which follows the |RoutingModel_V3| interface).
 
-Base model:
+Available models:
 
 .. toctree::
    :maxdepth: 1
 
    sw1d
-
-Application models:
-
-.. toctree::
-   :maxdepth: 1
-
-   Channel <sw1d_channel>
-   Network <sw1d_network>
-   Storage <sw1d_storage>
-   Q-In <sw1d_q_in>
-   LIAS <sw1d_lias>
-   LIAS/Sluice <sw1d_lias_sluice>
-   Pump <sw1d_pump>
-   Q-Out <sw1d_q_out>
-   Weir-Out <sw1d_weir_out>
-   Gate-Out <sw1d_gate_out>
+   sw1d_channel
+   sw1d_network
+   sw1d_storage
+   sw1d_q_in
+   sw1d_lias
+   sw1d_lias_sluice
+   sw1d_pump
+   sw1d_q_out
+   sw1d_weir_out
+   sw1d_gate_out

hydpy/models/sw1d/__init__.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-"""HydPy-SW1D provides features for implementing models for approximating the
+"""|sw1d.DOCNAME.long| provides features for implementing models for approximating the
 1-dimensional shallow water equations in a "hydrodynamic" manner to account for
 situations like backwater effects that "hydrological" methods cannot handle well."""
 # import...

hydpy/models/sw1d/sw1d_model.py

@@ -3260,7 +3260,9 @@ class Update_Storage_V1(modeltools.AutoMethod):
 
 
 class Model(modeltools.SubstepModel):
-    """The HydPy-SW-1D model."""
+    """|sw1d.DOCNAME.complete|."""
+
+    DOCNAME = modeltools.DocName(short="SW1D")
 
     INLET_METHODS = (
         Pick_Inflow_V1,
@@ -3399,8 +3401,8 @@ class Model(modeltools.SubstepModel):
 
 
 class Main_CrossSectionModel_V2(modeltools.AdHocModel):
-    """Base class for HydPy-SW1D models that use submodels named `crosssection` and
-    comply with the |CrossSectionModel_V2| interface."""
+    """Base class for |sw1d.DOCNAME.long| models that use submodels named
+    `crosssection` and comply with the |CrossSectionModel_V2| interface."""
 
     crosssection: modeltools.SubmodelProperty[routinginterfaces.CrossSectionModel_V2]
     crosssection_is_mainmodel = modeltools.SubmodelIsMainmodelProperty()

hydpy/models/sw1d_channel.py

@@ -4,7 +4,7 @@
 .. _`German Federal Institute of Hydrology (BfG)`: https://www.bafg.de/EN
 .. _`LIAS issue on GitHub`: https://github.com/hydpy-dev/hydpy/issues/98
 
-The *HydPy-SW1D* model family member |sw1d_channel| allows combining different
+The |sw1d.DOCNAME.long| model family member |sw1d_channel| allows combining different
 storage and routing submodels for representing the 1-dimensional flow processes within
 a single channel reach.
 
@@ -40,8 +40,8 @@
 A valid |sw1d_channel| configuration requires one storage model that complies with the
 |StorageModel_V1| at each segment.  We prepare |sw1d_storage| submodels with identical
 channel bottom elevations and rectangular profiles.  As for other submodels of the
-HydPy-SW1D model family, one specifies such geometries by sub-submodels that comply
-with |CrossSectionModel_V2| interface.  Here, we select |wq_trapeze|:
+|sw1d.DOCNAME.long| model family, one specifies such geometries by sub-submodels that
+comply with |CrossSectionModel_V2| interface.  Here, we select |wq_trapeze|:
 
 >>> for i, length_ in enumerate(lengths):
 ...     with model.add_storagemodel_v1("sw1d_storage", position=i):
@@ -1583,8 +1583,15 @@
 
 
 class Model(modeltools.SubstepModel, routinginterfaces.ChannelModel_V1):
-    """A "user model" for preparing river networks to simulate routing based on the
-    1-dimensional shallow water equations."""
+    """|sw1d_channel.DOCNAME.complete|."""
+
+    DOCNAME = modeltools.DocName(
+        short="SW1D-Channel",
+        description=(
+            '"user model" for preparing single channels that will be combined and '
+            "solved by HydPy-SW1D-Network"
+        ),
+    )
 
     INLET_METHODS = (sw1d_model.Trigger_Preprocessing_V1,)
     RECEIVER_METHODS = ()

hydpy/models/sw1d_gate_out.py

@@ -1,8 +1,8 @@
 # -*- coding: utf-8 -*-
 # pylint: disable=line-too-long, unused-wildcard-import
 """
-The *HydPy-SW1D* model family member |sw1d_gate_out| is a routing submodel, which
-calculates the flow under a submerged gate.
+The |sw1d.DOCNAME.long| model family member |sw1d_gate_out| is a routing submodel,
+which calculates the flow under a submerged gate.
 
 Principally, |sw1d_gate_out| is similar to |sw1d_weir_out|, which calculates the flow
 over a weir.  Both models must be placed at a network outlet.  However, while
@@ -540,8 +540,14 @@
 
 
 class Model(modeltools.AdHocModel, routinginterfaces.RoutingModel_V3):
-    """A routing submodel for calculating "longitudinal" outflow from the last segment
-    of a channel as the flow under a submerged gate."""
+    """|sw1d_gate_out.DOCNAME.complete|."""
+
+    DOCNAME = modeltools.DocName(
+        short="SW1D-Gate-Out",
+        description=(
+            "submodel for calculating flow under a submerged gate at a channel outlet"
+        ),
+    )
 
     INLET_METHODS = ()
     RECEIVER_METHODS = ()

hydpy/models/sw1d_lias.py

@@ -1,9 +1,9 @@
 # -*- coding: utf-8 -*-
 # pylint: disable=unused-wildcard-import
 """
-The *HydPy-SW1D* model family member |sw1d_lias| is a routing submodel that allows
-applying a 1-dimensional version of the "local inertial approximation of the shallow
-water equations" introduced by :cite:t:`ref-Bates2010` and "stabilised" by
+The |sw1d.DOCNAME.long| model family member |sw1d_lias| is a routing submodel that
+allows applying a 1-dimensional version of the "local inertial approximation of the
+shallow water equations" introduced by :cite:t:`ref-Bates2010` and "stabilised" by
 :cite:t:`ref-Almeida2012`.
 
 Please refer to the documentation of the "user model" |sw1d_channel| and the
@@ -21,9 +21,15 @@
 
 
 class Model(sw1d_model.Main_CrossSectionModel_V2, routinginterfaces.RoutingModel_V2):
-    """A routing submodel based on the "local inertial approximation of the shallow
-    water equations" introduced by :cite:t:`ref-Bates2010` and "stabilised" by
-    :cite:t:`ref-Almeida2012`."""
+    """|sw1d_lias.DOCNAME.complete|."""
+
+    DOCNAME = modeltools.DocName(
+        short="SW1D-LIAS",
+        description=(
+            "submodel for calculating the discharge between two channel segments "
+            "based on Bates et al. (2010) and Almeida et al. (2012)"
+        ),
+    )
 
     INLET_METHODS = ()
     RECEIVER_METHODS = ()

hydpy/models/sw1d_lias_sluice.py

@@ -1,8 +1,8 @@
 # -*- coding: utf-8 -*-
 # pylint: disable=line-too-long, unused-wildcard-import
 """
-The *HydPy-SW1D* model family member |sw1d_lias_sluice| extends the routing submodel
-|sw1d_lias| with simple sluice functionalities.
+The |sw1d.DOCNAME.long| model family member |sw1d_lias_sluice| extends the routing
+submodel |sw1d_lias| with simple sluice functionalities.
 
 The main model |sw1d_channel| documentation explains |sw1d_lias| depth.  Here, we limit
 the discussion to some of the additional features of |sw1d_lias_sluice|.  Please also
@@ -447,9 +447,14 @@
 
 
 class Model(sw1d_model.Main_CrossSectionModel_V2, routinginterfaces.RoutingModel_V2):
-    """A routing submodel combining the "local inertial approximation of the shallow
-    water equations" introduced by :cite:t:`ref-Bates2010` and "stabilised" by
-    :cite:t:`ref-Almeida2012` with simple sluice functionalities."""
+    """|sw1d_lias_sluice.DOCNAME.complete|."""
+
+    DOCNAME = modeltools.DocName(
+        short="SW1D-LIAS/Sluice",
+        description=(
+            "submodel that extends HydPy-SW1D-LIAS with sluice functionalities"
+        ),
+    )
 
     INLET_METHODS = ()
     RECEIVER_METHODS = ()

hydpy/models/sw1d_network.py

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 # pylint: disable=line-too-long, unused-wildcard-import
 """
-The *HydPy-SW1D* model family member |sw1d_network| allows combining different
+The |sw1d.DOCNAME.long| model family member |sw1d_network| allows combining different
 storage and routing submodels for representing the 1-dimensional flow processes within
 a complete channel network.
 
@@ -657,8 +657,15 @@
 
 
 class Model(modeltools.SubstepModel):
-    """A "composite model" for solving the 1-dimensional shallow water equations in
-    complex channel networks."""
+    """|sw1d_network.DOCNAME.complete|."""
+
+    DOCNAME = modeltools.DocName(
+        short="SW1D-Network",
+        description=(
+            '"composite model" for solving the 1-dimensional shallow water equations '
+            "in channel networks"
+        ),
+    )
 
     COMPOSITE = True
     """|sw1d_network| is a composite model.  (One usually only works with it 

hydpy/models/sw1d_pump.py

@@ -1,8 +1,8 @@
 # -*- coding: utf-8 -*-
 # pylint: disable=line-too-long, unused-wildcard-import
 """
-The *HydPy-SW1D* model family member |sw1d_pump| is a routing submodel that calculates
-water pumping from one channel segment into another.
+The |sw1d.DOCNAME.long| model family member |sw1d_pump| is a routing submodel that
+calculates water pumping from one channel segment into another.
 
 Integration tests
 =================
@@ -371,8 +371,12 @@
 
 
 class Model(sw1d_model.Main_CrossSectionModel_V2, routinginterfaces.RoutingModel_V2):
-    """A routing submodel for calculating water pumping from one channel segment into
-    another."""
+    """|sw1d_pump.DOCNAME.complete|."""
+
+    DOCNAME = modeltools.DocName(
+        short="SW1D-Pump",
+        description="submodel for pumping water between two channel segments",
+    )
 
     INLET_METHODS = ()
     RECEIVER_METHODS = ()

hydpy/models/sw1d_q_in.py

@@ -1,8 +1,8 @@
 # -*- coding: utf-8 -*-
 # pylint: disable=unused-wildcard-import
 """
-The *HydPy-SW1D* model family member |sw1d_q_in| is a simple routing submodel, which
-allows taking observed or previously simulated discharge series as "longitudinal"
+The |sw1d.DOCNAME.long| model family member |sw1d_q_in| is a simple routing submodel,
+which allows taking observed or previously simulated discharge series as "longitudinal"
 channel inflow.
 
 Please refer to the documentation of the "user model" |sw1d_channel| and the
@@ -20,8 +20,12 @@
 
 
 class Model(sw1d_model.Main_CrossSectionModel_V2, routinginterfaces.RoutingModel_V1):
-    """A simple routing submodel for inserting "longitudinal" inflow into the first
-    segment of a channel."""
+    """|sw1d_q_in.DOCNAME.complete|."""
+
+    DOCNAME = modeltools.DocName(
+        short="SW1D-Q-In",
+        description="submodel for adding pre-determined discharge to a channel inlet",
+    )
 
     INLET_METHODS = ()
     RECEIVER_METHODS = ()

hydpy/models/sw1d_q_out.py

@@ -1,8 +1,8 @@
 # -*- coding: utf-8 -*-
 # pylint: disable=unused-wildcard-import
 """
-The *HydPy-SW1D* model family member |sw1d_q_out| is a simple routing submodel, which
-allows taking observed or previously simulated discharge series as "longitudinal"
+The |sw1d.DOCNAME.long| model family member |sw1d_q_out| is a simple routing submodel,
+which allows taking observed or previously simulated discharge series as "longitudinal"
 channel outflow.
 
 Please refer to the documentation of the "composite model" |sw1d_network|, where we
@@ -20,8 +20,14 @@
 
 
 class Model(sw1d_model.Main_CrossSectionModel_V2, routinginterfaces.RoutingModel_V3):
-    """A simple routing submodel for removing "longitudinal" outflow from the last
-    segment of a channel."""
+    """|sw1d_q_out.DOCNAME.complete|."""
+
+    DOCNAME = modeltools.DocName(
+        short="SW1D-Q-Out",
+        description=(
+            "submodel for subtracting pre-determined discharge from a channel outlet"
+        ),
+    )
 
     INLET_METHODS = ()
     RECEIVER_METHODS = ()

hydpy/models/sw1d_storage.py

@@ -1,7 +1,8 @@
 # -*- coding: utf-8 -*-
 """
-The *HydPy-SW1D* model family member |sw1d_storage| is a storage submodel for keeping
-track of the water amount stored in a channel segment and calculating the water level.
+The |sw1d.DOCNAME.long| model family member |sw1d_storage| is a storage submodel for
+keeping track of the water amount stored in a channel segment and calculating the water
+level.
 
 Please refer to the documentation of the "user model" |sw1d_channel| and the
 "composite model" |sw1d_network|, where we demonstrate and discuss |sw1d_storage| in
@@ -19,8 +20,12 @@
 
 
 class Model(sw1d_model.Main_CrossSectionModel_V2, routinginterfaces.StorageModel_V1):
-    """A storage submodel for calculating a single channel segment's water balance and
-    water level."""
+    """|sw1d_storage.DOCNAME.complete|."""
+
+    DOCNAME = modeltools.DocName(
+        short="SW1D-Storage",
+        description="submodel for calculating a single channel segment's water balance",
+    )
 
     INLET_METHODS = ()
     RECEIVER_METHODS = ()

hydpy/models/sw1d_weir_out.py

@@ -1,8 +1,8 @@
 # -*- coding: utf-8 -*-
 # pylint: disable=unused-wildcard-import
 """
-The *HydPy-SW1D* model family member |sw1d_weir_out| is a routing submodel, which
-calculates the free flow over a weir out of a channel after Poleni.
+The |sw1d.DOCNAME.long| model family member |sw1d_weir_out| is a routing submodel,
+which calculates the free flow over a weir out of a channel after Poleni.
 
 Please refer to the documentation of the "user model" |sw1d_channel| and the
 "composite model" |sw1d_network|, where we demonstrate and discuss |sw1d_weir_out| in
@@ -19,8 +19,12 @@
 
 
 class Model(modeltools.AdHocModel, routinginterfaces.RoutingModel_V3):
-    """A routing submodel for calculating "longitudinal" outflow from the last segment
-    of a channel as free flow over a weir after Poleni."""
+    """|sw1d_weir_out.DOCNAME.complete|."""
+
+    DOCNAME = modeltools.DocName(
+        short="SW1D-Weir-Out",
+        description="submodel for calculating free weir flow at a channel outlet",
+    )
 
     INLET_METHODS = ()
     RECEIVER_METHODS = ()