Docs: overwrite run_ribasim (#2929)

Fixes #2700

We overwrite the ribasim function with our hidden function that runs the
julia code, so we don't need to have a ribasim binary at doc build time.

Author: visr

docs/getting-started/examples.qmd

@@ -5,16 +5,6 @@ jupyter: python3
 
 This is an overview of example codes to set-up and run models.
 
-```{python}
-#| eval: false
-from ribasim import run_ribasim
-```
-
-```{python}
-#| include: false
-%run ../run_ribasim.py
-```
-
 # Basic model with static forcing
 
 ```{python}
@@ -31,7 +21,7 @@ from pathlib import Path
 import matplotlib.pyplot as plt
 import numpy as np
 import pandas as pd
-from ribasim import Allocation, Model, Node, Solver
+from ribasim import Allocation, Model, Node, Solver, run_ribasim
 from ribasim.config import Experimental
 from ribasim.nodes import (
     basin,
@@ -51,6 +41,11 @@ from ribasim.nodes import (
 from shapely.geometry import Point
 ```
 
+```{python}
+#| include: false
+%run ../run_ribasim.py
+```
+
 ```{python}
 datadir = Path("data")
 shutil.rmtree(datadir, ignore_errors=True)

docs/getting-started/tutorial/irrigation-demand.qmd

@@ -3,24 +3,14 @@ title: Irrigation demand
 jupyter: python3
 ---
 
-```{python}
-#| eval: false
-from ribasim import run_ribasim
-```
-
-```{python}
-#| include: false
-%run ../../run_ribasim.py
-```
-
 ```{python}
 from pathlib import Path
 
 import matplotlib.pyplot as plt
 import pandas as pd
 import plotly.express as px
 import xarray as xr
-from ribasim import Model, Node
+from ribasim import Model, Node, run_ribasim
 from ribasim.nodes import (
     basin,
     flow_boundary,
@@ -30,6 +20,11 @@ from ribasim.nodes import (
 from shapely.geometry import Point
 ```
 
+```{python}
+#| include: false
+%run ../../run_ribasim.py
+```
+
 ```{python}
 base_dir = Path("crystal-basin")
 

docs/getting-started/tutorial/natural-flow.qmd

@@ -3,16 +3,6 @@ title: Natural flow
 jupyter: python3
 ---
 
-```{python}
-#| eval: false
-from ribasim import run_ribasim
-```
-
-```{python}
-#| include: false
-%run ../../run_ribasim.py
-```
-
 # Introduction
 Welcome to Ribasim!
 This tutorial will help you get started with the basics of using Ribasim for river basin simulation.
@@ -63,11 +53,16 @@ from pathlib import Path
 import matplotlib.pyplot as plt
 import pandas as pd
 import xarray as xr
-from ribasim import Model, Node
+from ribasim import Model, Node, run_ribasim
 from ribasim.nodes import basin, flow_boundary, tabulated_rating_curve
 from shapely.geometry import Point
 ```
 
+```{python}
+#| include: false
+%run ../../run_ribasim.py
+```
+
 ### Setup paths and model configuration
 Reference the paths of the Ribasim installation and model directory and define the time period.
 The used simulation period is defined by the `starttime` and `endtime` of the model, not by the input timeseries.

docs/getting-started/tutorial/reservoir.qmd

@@ -3,24 +3,14 @@ title: Reservoir
 jupyter: python3
 ---
 
-```{python}
-#| eval: false
-from ribasim import run_ribasim
-```
-
-```{python}
-#| include: false
-%run ../../run_ribasim.py
-```
-
 ```{python}
 from pathlib import Path
 
 import matplotlib.pyplot as plt
 import pandas as pd
 import plotly.express as px
 import xarray as xr
-from ribasim import Model, Node
+from ribasim import Model, Node, run_ribasim
 from ribasim.nodes import (
     basin,
     flow_boundary,
@@ -30,6 +20,11 @@ from ribasim.nodes import (
 from shapely.geometry import Point
 ```
 
+```{python}
+#| include: false
+%run ../../run_ribasim.py
+```
+
 ```{python}
 base_dir = Path("crystal-basin")
 

docs/guide/delwaq.qmd

@@ -3,16 +3,6 @@ title: Ribasim Delwaq coupling
 jupyter: python3
 ---
 
-```{python}
-#| eval: false
-from ribasim import run_ribasim
-```
-
-```{python}
-#| include: false
-%run ../run_ribasim.py
-```
-
 In order to generate the Delwaq input files, we need a completed Ribasim simulation (typically one with a results folder) that ideally also includes some substances and initial concentrations. Let's take the basic test model for example, which already has set some initial concentrations.
 
 All testmodels can be [downloaded from here](/getting-started/install.qmd).
@@ -30,7 +20,7 @@ assert toml_path.is_file()
 This Ribasim model already has substance concentrations for `Cl` and `Tracer` in the input tables, and we will use these to generate the Delwaq input files.
 
 ```{python}
-from ribasim import Model
+from ribasim import Model, run_ribasim
 
 model = Model.read(toml_path)
 
@@ -41,6 +31,11 @@ display(model.level_boundary.concentration)  # level boundaries
 model.plot();  # for later comparison
 ```
 
+```{python}
+#| include: false
+%run ../run_ribasim.py
+```
+
 ```{python}
 model.basin.profile
 ```

docs/run_ribasim.py

@@ -8,10 +8,9 @@
 In a file where multiple simulations are run this has the benefit
 of only needing to start Julia once, compared to `subprocess.run`.
 
-Since Ribasim Python also has `run_ribasim`, we can include
-this script in a hidden evaluated cell, and put `from ribasim import run_ribasim`
-in a visible unevaluated cell. That way we can run this version on CI but
-it looks like we run the Ribasim Python version.
+Since Ribasim Python also has `run_ribasim`, we can include this script
+in a hidden evaluated cell, after `from ribasim import run_ribasim`.
+That way we can run this version on CI but it looks like we run the Ribasim Python version.
 """
 
 from pathlib import Path