Run quick start in docs (#1811)

Fixes #1807.

Rather than having docs with code that doesn't run and output in static
images, this intends to run the notebook as part of the docs generation
just like example.ipynb.

I am also making more edits which I'll describe later.

---------

Co-authored-by: Bart de Koning <[email protected]>

.pre-commit-config.yaml

@@ -4,7 +4,6 @@ repos:
     hooks:
       - id: check-added-large-files
       - id: check-case-conflict
-      - id: check-json
       - id: check-yaml
       - id: check-toml
       - id: check-merge-conflict

.vscode/settings.json

@@ -4,8 +4,9 @@
     },
     "notebook.formatOnSave.enabled": false,
     "notebook.codeActionsOnSave": {
-        "source.fixAll.ruff": true,
-        "source.organizeImports.ruff": true
+        // https://github.com/astral-sh/ruff-vscode/issues/593
+        "source.fixAll.ruff": "never",
+        "source.organizeImports.ruff": "never"
     },
     "[python]": {
         "editor.defaultFormatter": "charliermarsh.ruff",

docs/.gitignore

@@ -2,6 +2,7 @@
 /_site/
 /site_libs/
 /reference/python/
+/tutorial/crystal-basin/
 guide/data/
 *.html
 objects.json

docs/_quarto.yml

@@ -10,8 +10,10 @@ website:
     left:
       - text: "Overview"
         file: index.qmd
+      - text: "Tutorials"
+        file: tutorial/natural-flow.ipynb
       - text: "How-to guides"
-        file: guide/quickstart.qmd
+        file: guide/examples.ipynb
       - text: "Concepts"
         file: concept/concept.qmd
       - text: "Reference"
@@ -31,9 +33,14 @@ website:
         - changelog.qmd
         - known_issues.qmd
 
+    - title: "Tutorials"
+      contents:
+        - tutorial/natural-flow.ipynb
+        - tutorial/irrigation-demand.ipynb
+        - tutorial/reservoir.ipynb
+
     - title: "How-to guides"
       contents:
-        - guide/quickstart.qmd
         - guide/examples.ipynb
         - guide/qgis.qmd
         - guide/coupling.qmd

docs/guide/examples.ipynb

@@ -405,19 +405,6 @@
     "ribasim basic/ribasim.toml\n",
     "```\n",
     "\n",
-    "From Python you can run it with:\n",
-    "\n",
-    "```python\n",
-    "import subprocess\n",
-    "result = subprocess.run([cli_path, toml_path], capture_output=True, encoding=\"utf-8\")\n",
-    "print(result.stderr)\n",
-    "result.check_returncode()\n",
-    "```\n",
-    "\n",
-    "Where `cli_path` is a string with either the full path to the Ribasim executable, like `r\"c:\\ribasim_windows\\ribasim\"`, or just `\"ribasim\"` in case you added the `ribasim_windows` folder to your PATH.\n",
-    "\n",
-    "The `print(result.stderr)` ensures you see the same logging and error messages that you would see in the terminal. And `result.check_returncode()` will throw an error when the simulation was not successful.\n",
-    "\n",
     "After running the model, read back the results:"
    ]
   },