Merge pull request #27 from ConnectedSystems/doc-example-update

Changes to clean up documentation

Author: ConnectedSystems

README.md

@@ -61,7 +61,8 @@ Note that since start of development, an updated dataset is incoming (currently
 
 > Fowler, K. J. A., Zhang, Z., and Hou, X.: CAMELS-AUS v2: updated hydrometeorological timeseries and landscape attributes for an enlarged set of catchments in Australia, Earth Syst. Sci. Data Discuss. [preprint], https://doi.org/10.5194/essd-2024-263, in review, 2024.
 
-Climate data was extracted from the [Long Paddock data silo](https://www.longpaddock.qld.gov.au/silo/)
+Climate data was sourced from the Climate [Change in Australia](https://www.climatechangeinaustralia.gov.au)
+data service. Additional data was extracted from the [Long Paddock data silo](https://www.longpaddock.qld.gov.au/silo/).
 
 ## Quick start (single node)
 
@@ -145,7 +146,7 @@ To display an overview of a node or network:
 
 ```julia
 julia> node
-Name: 406219 [BilinearNode]
+Name: 406219 [IHACRESBilinearNode]
 Area: 1985.73
 ┌──────────────┬───────────┬─────────────┬─────────────┐
 │    Parameter │     Value │ Lower Bound │ Upper Bound │
@@ -203,14 +204,8 @@ using Streamfall
 sn = load_network("Example Network", "../test/data/campaspe/campaspe_network.yml")
 
 # Load climate data, in this case from a CSV file with data for all nodes.
-climate_data = CSV.read(
-    "../test/data/campaspe/climate/climate_historic.csv", DataFrame,
-    comment="#",
-    dateformat="YYYY-mm-dd"
-)
-
 # Indicate which columns are precipitation and evaporation data based on partial identifiers
-climate = Climate(climate_data, "_rain", "_evap")
+climate = Climate("../test/data/campaspe/climate/climate.csv", "_rain", "_evap")
 
 # This runs an entire stream network
 @info "Running an example stream..."
@@ -252,6 +247,9 @@ through all relevant nodes upstream.
 ```julia
 @info "Running example stream..."
 timesteps = sim_length(climate)
+
+reset!(sn)
+prep_state!(sn, timesteps)
 for ts in (1:timesteps)
     for outlet in outlets
         run_node!(sn, outlet, climate, ts)

docs/make.jl

@@ -14,27 +14,36 @@ makedocs(sitename="Streamfall Documentation",
     pages = [
         "index.md",
         "primer.md",
-        "Nodes" => [
-            "Node.md",
-            "IHACRES.md",
-            "HyMod.md",
-            "GR4J.md",
-            "SYMHYD.md",
-            "Dam.md"
-        ],
-        "network.md",
-        "use_methods.md",
-        "metrics.md",
+        "expected_data_formats.md",
         "Examples" => [
+            "examples/examples.md",
+            "examples/node_creation.md",
+            "examples/network_loading.md",
             "Calibration" => [
-                "calibration_setup.md",
-                "calibration.md",
+                # "examples/calibration_setup.md",
+                "examples/calibration.md",
+            ],
+            "Model evaluation" => [
+                "examples/simple_showcase.md",
+                "examples/model_comparison.md",
+                "examples/simple_multisystem.md",
+            ]
+        ],
+        "API" => [
+            "metrics.md",
+            "Nodes" => [
+                "API/nodes/Node.md",
+                "API/nodes/IHACRES.md",
+                "API/nodes/HyMod.md",
+                "API/nodes/GR4J.md",
+                "API/nodes/SYMHYD.md",
+                "API/nodes/Dam.md"
             ],
-            "simple_showcase.md",
-            "model_comparison.md",
-            # "multisystem_showcase.md",
+            "API/plotting.md",
+            "API/network.md",
+            "API/climate.md",
+            "API/use_methods.md"
         ]
-
     ]
 )
 

docs/src/API/climate.md

@@ -0,0 +1,7 @@
+# Climate
+
+```@autodocs
+Modules = [Streamfall]
+Order   = [:function, :type]
+Pages   = ["Climate.jl"]
+```

docs/src/network.md docs/src/API/network.mddocs/src/network.md renamed to docs/src/API/network.md

@@ -3,5 +3,5 @@
 ```@autodocs
 Modules = [Streamfall]
 Order   = [:function, :type]
-Pages   = ["GR4JNode.jl"]
+Pages   = ["Nodes/GR4J/GR4JNode.jl"]
 ```

docs/src/Dam.md docs/src/API/nodes/Dam.mddocs/src/Dam.md renamed to docs/src/API/nodes/Dam.md

@@ -3,5 +3,5 @@
 ```@autodocs
 Modules = [Streamfall]
 Order   = [:function, :type]
-Pages   = ["HyModNode.jl"]
+Pages   = ["Nodes/HyMod/HyModNode.jl"]
 ```

docs/src/EnsembleNode.md docs/src/API/nodes/EnsembleNode.mddocs/src/EnsembleNode.md renamed to docs/src/API/nodes/EnsembleNode.md

@@ -3,7 +3,7 @@
 ```@autodocs
 Modules = [Streamfall]
 Order   = [:function, :type]
-Pages   = ["IHACRESNode.jl"]
+Pages   = ["Nodes/IHACRES/IHACRESNode.jl"]
 ```
 
 ### IHACRES - Expuh

docs/src/GR4J.md docs/src/API/nodes/GR4J.mddocs/src/GR4J.md renamed to docs/src/API/nodes/GR4J.md

@@ -3,5 +3,5 @@
 ```@autodocs
 Modules = [Streamfall]
 Order   = [:function, :type]
-Pages   = ["Node.jl"]
+Pages   = ["Nodes/Node.jl"]
 ```