Update examples cli (#1062)

Co-authored-by: Sam Vente <[email protected]>

docs/guides/advanced_user/model_components.rst

@@ -22,61 +22,8 @@ and the write permissions as well as other components. This means that component
 effectively exit outside of a model.
 
 There are basically two ways to add a component to a model: using the workflow yaml and
-using the python interface.
-
-Adding components using the workflow yaml
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-In a workflow file, all the components that a model needs to have (appart from any
-default components your plugin has already provided) must be declared upfront. This is
-done with the ``global`` keyword (typcially placed at the start of the file)
-
-it should look like this
-
-.. code-block:: yaml
-
-    global:
-        components:
-            grid:
-                type: GridComponent
-            config:
-                type: ConfigComponent
-            forcing:
-                type: SpatialDatasetsComponent
-                region_component: grid
-        region_component: grid
-
-
-here you can see that ``components`` should take a mapping where the keys are the name
-the component will have. These must then again take a mapping that specifies at least
-the type of component. The name of the component type should correspond to the python
-class name.
-
-An additional point of note is that spacial components (such as ``forcing`` and
-``grid``) in the example above, can either define their own region (``grid``) or derive
-their region from another component (``forcing``). This can be done by specifying the
-``region_component`` key, and should refer to the name of the spacial component you wish
-to use. You can also specify which spacial component the model should derive it's region
-from. If you have only one spacial component, this information may be omitted, but if
-you have multiple (as in the example above) you must also specify which component the
-model should derive it's region from.
-
-After you have specified the components that should be added to your model in the
-``global`` key, you can use them in the steps of your workflow like so:
-
-.. code-block:: yaml
-
-    steps:
-        - grid.add_data_from_constant:
-            constant: 0.01
-            name: "c1"
-            nodata: -99.0
-        - ...
-
-in the example above ``grid`` is the name of the component and
-``add_data_from_constant`` is the function on it that you want to call. Please check the
-specific component for what functions are available. Note that only functions that have
-the ``@hydromt_step`` decorator are available to use from the yaml workflow.
+using the python interface. For more detail on how components are created and accessed
+from the workflow file see :ref:`this page <model_workflow>`
 
 Adding components using the Python interface
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

docs/guides/core_dev/contributing.rst

@@ -227,7 +227,7 @@ The HydroMT :ref:`Model class <model_api>` consists of several methods and attri
 To implement HydroMT for a specific model kernel/software, a child class named `<Name>Model` (e.g. SfincsModel for Sfincs)
 should be created with model-specific data readers, writers and setup methods as is appropriate.
 
-- :ref:`Model data components <model_interface>` are data attributes which together define a model instance and
+- :ref:`Model data components </guides/advanced_user/model_components.rst>` are data attributes which together define a model instance and
   are identical for all models. Each component represents a specific model component and is parsed to a specific
   Python data object that should adhere to certain specifications. For instance, the ``grid`` component represent
   all static regular grids of a model in a :py:class:`xarray.Dataset` object.

docs/guides/user_guide/model_workflow.rst

@@ -3,4 +3,76 @@
 Creating a Model Workflow
 =========================
 
-TBC
+A model workflow (the ``.yaml`` file that tells hydromt what todo) consists of three
+main sections:
+
+1. ``modeltype``
+2. ``global``
+3. ``steps``
+
+The model type tells hydromt which model to use. In the case of using hydromt core,
+``model`` is the only option but if you have plugins installed those will probably
+provide other options as well. You can discover which options you have installed with
+the command ``hydromt --models``.
+
+The global is where you provide any configuration that the model will need at
+initialization. This is where you for example, can (and must in the case of core) add
+components, and tell the model which spacial component should be used to figure out what
+the model region is.
+
+In a workflow file, all the components that a model needs to have (appart from any
+default components your plugin has already provided) must be declared upfront. This is
+done with the ``global`` keyword (typcially placed at the start of the file)
+
+it should look like this
+
+.. code-block:: yaml
+
+    global:
+        components:
+            grid:
+                type: GridComponent
+            config:
+                type: ConfigComponent
+            forcing:
+                type: SpatialDatasetsComponent
+                region_component: grid
+        region_component: grid
+
+
+here you can see that ``components`` should take a mapping where the keys are the name
+the component will have. These must then again take a mapping that specifies at least
+the type of component. The name of the component type should correspond to the python
+class name.
+
+An additional point of note is that spacial components (such as ``forcing`` and
+``grid``) in the example above, can either define their own region (``grid``) or derive
+their region from another component (``forcing``). This can be done by specifying the
+``region_component`` key, and should refer to the name of the spacial component you wish
+to use. You can also specify which spacial component the model should derive it's region
+from. If you have only one spacial component, this information may be omitted, but if
+you have multiple (as in the example above) you must also specify which component the
+model should derive it's region from.
+
+
+Finally there is the ``steps`` part of the workflow. This should be a list, where each
+list item should be a name of a function you want to run, followed by any arguments you
+want to pass to that function. You can use the ``.`` syntax to call functions on
+components, or omit this if the function you want to call is defined on the model.
+
+For example, after you have specified the components that should be added to your model
+in the ``global`` key, you can use them in the steps of your workflow like so:
+
+.. code-block:: yaml
+
+    steps:
+        - grid.add_data_from_constant:
+            constant: 0.01
+            name: "c1"
+            nodata: -99.0
+        - ...
+
+in the example above ``grid`` is the name of the component and
+``add_data_from_constant`` is the function on it that you want to call. Please check the
+specific component for what functions are available. Note that only functions that have
+the ``@hydromt_step`` decorator are available to use from the yaml workflow.

examples/working_with_meshcomponent.ipynb

@@ -0,0 +1,122 @@
+{
+ "cells": [
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Example: Working with mesh components"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The main feature of HydroMT is to facilitate the process of building and analyzing spatial geoscientific models with a focus on water system models. It does so by automating the workflow to go from raw data to a complete model instance which is ready to run and to analyse model results once the simulation has finished. \n",
+    "\n",
+    "This notebook will explore how to work with mesh models."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# import hydromt\n",
+    "import hydromt\n",
+    "\n",
+    "# other imports\n",
+    "import matplotlib.pyplot as plt\n",
+    "import geopandas as gpd"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Check if `MeshComponent` comes from"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "To know which models are available within your active environment, you can use global `PLUGINS` variable in hydromt"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Model classes: Model plugins:\n",
+      "\t- model (hydromt 1.0.0a0)\n",
+      "Model components: Component plugins:\n",
+      "\t- ConfigComponent (hydromt 1.0.0a0)\n",
+      "\t- DatasetsComponent (hydromt 1.0.0a0)\n",
+      "\t- GeomsComponent (hydromt 1.0.0a0)\n",
+      "\t- GridComponent (hydromt 1.0.0a0)\n",
+      "\t- MeshComponent (hydromt 1.0.0a0)\n",
+      "\t- SpatialDatasetsComponent (hydromt 1.0.0a0)\n",
+      "\t- TablesComponent (hydromt 1.0.0a0)\n",
+      "\t- VectorComponent (hydromt 1.0.0a0)\n"
+     ]
+    }
+   ],
+   "source": [
+    "# generic model classes\n",
+    "print(f\"Model classes: {hydromt.PLUGINS.model_summary()}\")\n",
+    "# model classes from external plugin\n",
+    "print(f\"Model components: {hydromt.PLUGINS.component_summary()}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "TBC"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.11.9"
+  },
+  "vscode": {
+   "interpreter": {
+    "hash": "3808d5b5b54949c7a0a707a38b0a689040fa9c90ab139a050e41373880719ab1"
+   }
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}