#246 Markdown file 'first steps' is converted to Jupyter notebook

docs/tutorials/first_steps.ipynb

@@ -0,0 +1,127 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# First steps\n",
+    "\n",
+    "This _first steps_ tutorial illustrates how to create a simple D-Flow FM model from scratch using the [HYDROLIB-core](https://github.com/Deltares/HYDROLIB-core). "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "/workspaces/hydrolib-core/hydrolib/core/io/structure/models.py:221: SyntaxWarning: \"is\" with a literal. Did you mean \"==\"?\n",
+      "  if self.type is \"compound\":\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Import HYDROLIB-core functionalities and setup D-Flow FM model\n",
+    "from hydrolib.core.io.structure.models import FlowDirection, StructureModel, Weir\n",
+    "from hydrolib.core.io.mdu.models import FMModel\n",
+    "\n",
+    "fm = FMModel()\n",
+    "fm.filepath = \"test.mdu\""
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Add some structures, note this is invalid because it doesn't \n",
+    "have a branch or coordinates yet, but it will work for demo purposes"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Add weir to the model and assign structure to D-Flow FM model \n",
+    "struc = Weir(branchId='someBranch', chainage = 123.0, allowedflowdir=FlowDirection.none, crestlevel=0.0)\n",
+    "struc.comments.crestlevel = \"This is a comment\"\n",
+    "fm.geometry.structurefile = [StructureModel(structure=[struc])]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Note that the creation of a `Weir` and other models always require\n",
+    "the use of keyword arguments. A `ValidationError` will be raised\n",
+    "when the model isn't correct or complete, for instance, in the case\n",
+    "that `StructureModel` was assigned directly to `structurefile` instead\n",
+    "of as a list.\n",
+    "\n",
+    "Now let's add this model to a DIMR config and save it."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from hydrolib.core.io.dimr.models import DIMR, FMComponent\n",
+    "from pathlib import Path\n",
+    "\n",
+    "dimr = DIMR()\n",
+    "dimr.component.append(\n",
+    "    FMComponent(name=\"test\", workingDir=\".\", inputfile=fm.filepath, model=fm)\n",
+    ")\n",
+    "\n",
+    "dimr.save(recurse=True)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The save on the top of the model hierarchy will result in saves of all child models,\n",
+    "so this results in four files (`dimr_config.xml`, `network.nc`, `structures.ini`,`test.mdu`)\n",
+    "in the working directory."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3.9.13 ('.venv': poetry)",
+   "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.9.13"
+  },
+  "orig_nbformat": 4,
+  "vscode": {
+   "interpreter": {
+    "hash": "82e465d5440b391da8d43d2f583b852925fd7bed0ed0d752c9688c1fce589220"
+   }
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

mkdocs.yml

@@ -22,6 +22,7 @@ theme:
     - navigation.top
 plugins:
   - search
+  - mkdocs-jupyter
   - autorefs
   - table-reader
   - macros:
@@ -82,7 +83,7 @@ nav:
       - Support:
           - guides/gettinghelp.md
   - Tutorials:
-      - tutorials/steps.md
+      - tutorials/first_steps.ipynb
       - tutorials/loading_and_saving_a_model.md
       - tutorials/dataframe_handling.md
       - tutorials/plotting_a_network.md