Alexis docs hackathon #1 Aug 23

docs/Manifest.toml

@@ -2,7 +2,7 @@
 
 julia_version = "1.10.5"
 manifest_format = "2.0"
-project_hash = "6c3f79ccae513840cc13b9ac947575c2305b507f"
+project_hash = "6b19e20727d983c28286d493d461a6afa5ff8e8c"
 
 [[deps.ADTypes]]
 git-tree-sha1 = "99a6f5d0ce1c7c6afdb759daa30226f71c54f6b0"
@@ -19,6 +19,16 @@ git-tree-sha1 = "574baf8110975760d391c710b6341da1afa48d8c"
 uuid = "a4c015fc-c6ff-483c-b24f-f7ea428134e9"
 version = "0.0.1"
 
+[[deps.About]]
+deps = ["InteractiveUtils", "JuliaSyntaxHighlighting", "PrecompileTools", "StyledStrings"]
+git-tree-sha1 = "3a94c01a1d7678f1c29b7d97216f5046f1ed1768"
+uuid = "69d22d85-9f48-4c46-bbbe-7ad8341ff72a"
+version = "1.0.0"
+weakdeps = ["Pkg"]
+
+    [deps.About.extensions]
+    PkgExt = "Pkg"
+
 [[deps.AbstractFFTs]]
 deps = ["LinearAlgebra"]
 git-tree-sha1 = "d92ad398961a3ed262d8bf04a1a2b8340f915fef"
@@ -1421,6 +1431,17 @@ git-tree-sha1 = "af433a10f3942e882d3c671aacb203e006a5808f"
 uuid = "9c1d0b0a-7046-5b2e-a33f-ea22f176ac7e"
 version = "0.2.1+0"
 
+[[deps.JuliaSyntax]]
+git-tree-sha1 = "956ac689b31cd871a48fbb70978b798c5e95018a"
+uuid = "70703baa-626e-46a2-a12c-08ffd08c73b4"
+version = "0.4.9"
+
+[[deps.JuliaSyntaxHighlighting]]
+deps = ["JuliaSyntax", "StyledStrings"]
+git-tree-sha1 = "19ecee1ea81c60156486a92b062e443b6bba60b7"
+uuid = "ac6e5ff7-fb65-4e79-a425-ec3bc9c03011"
+version = "0.1.0"
+
 [[deps.JuliaVariables]]
 deps = ["MLStyle", "NameResolution"]
 git-tree-sha1 = "49fb3cb53362ddadb4415e9b73926d6b40709e70"
@@ -1871,6 +1892,12 @@ git-tree-sha1 = "c13304c81eec1ed3af7fc20e75fb6b26092a1102"
 uuid = "442fdcdd-2543-5da2-b0f3-8c86c306513e"
 version = "0.3.2"
 
+[[deps.MethodAnalysis]]
+deps = ["AbstractTrees"]
+git-tree-sha1 = "c2ee9b8f036c951f9ed0a47503a7f7dc0905b256"
+uuid = "85b6ec6f-f7df-4429-9514-a64bcd9ee824"
+version = "0.4.13"
+
 [[deps.MicroCollections]]
 deps = ["BangBang", "InitialValues", "Setfield"]
 git-tree-sha1 = "629afd7d10dbc6935ec59b32daeb33bc4460a42e"
@@ -2797,6 +2824,12 @@ weakdeps = ["Adapt", "GPUArraysCore", "SparseArrays", "StaticArrays"]
     StructArraysSparseArraysExt = "SparseArrays"
     StructArraysStaticArraysExt = "StaticArrays"
 
+[[deps.StyledStrings]]
+deps = ["PrecompileTools", "TOML"]
+git-tree-sha1 = "711c9650010c95814911c2005ea04e70e70e65ed"
+uuid = "f489334b-da3d-4c2e-b8f0-e476e12c162b"
+version = "1.0.3"
+
 [[deps.SuiteSparse]]
 deps = ["Libdl", "LinearAlgebra", "Serialization", "SparseArrays"]
 uuid = "4607b0f0-06f3-5cda-b6b1-a6196a1729e9"

docs/Project.toml

@@ -1,4 +1,6 @@
 [deps]
+About = "69d22d85-9f48-4c46-bbbe-7ad8341ff72a"
+AbstractTrees = "1520ce14-60c1-5f80-bbc7-55ef81b5835c"
 CSV = "336ed68f-0bac-5ca0-87d4-7b16caf5d00b"
 CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
 ClimaCore = "d414da3d-4745-48bb-8d80-42e94e092884"
@@ -19,6 +21,7 @@ InteractiveUtils = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
 Interpolations = "a98d9a8b-a2ab-59e6-89dd-64a1c18fca59"
 JSON = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
 Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
+MethodAnalysis = "85b6ec6f-f7df-4429-9514-a64bcd9ee824"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
 PrettyTables = "08abe8d2-0d0c-5749-adfa-8a2ac140af0d"
 SciMLBase = "0bca4576-84f4-4d90-8ffe-ffa030f20462"

docs/list_tutorials.jl

@@ -0,0 +1,34 @@
+tutorials = [
+    "Running simulations" => [
+        "Bucket LSM" => [
+            "standalone/Bucket/bucket_tutorial.jl",
+            "standalone/Bucket/coupled_bucket.jl",
+        ],
+        "Soil modeling" => [
+            "Boundary conditions" => "standalone/Soil/boundary_conditions.jl",
+            "Richards Equation" => "standalone/Soil/richards_equation.jl",
+            "Energy and Hydrology" => "standalone/Soil/soil_energy_hydrology.jl",
+            "Phase Changes" => "standalone/Soil/freezing_front.jl",
+            "Layered Soil" => "standalone/Soil/layered_soil.jl",
+            "Coarse Sand Evaporation" => "standalone/Soil/evaporation.jl",
+            "Gilat Loess Evaporation" => "standalone/Soil/evaporation_gilat_loess.jl",
+            "Bare soil site" => "standalone/Soil/sublimation.jl",
+        ],
+        "Canopy modeling" => [
+            "Standalone Canopy" => "standalone/Canopy/canopy_tutorial.jl",
+        ],
+        "Integrated soil+canopy modeling" => [
+            "Coupled Canopy and Soil" => "integrated/soil_canopy_tutorial.jl",
+        ],
+        "Snow Modeling" => [
+            "standalone/Snow/base_tutorial.jl",
+            "standalone/Snow/data_tutorial.jl",
+        ],
+    ],
+    "For model developers" => [
+        "Intro to standalone models" => "standalone/Usage/model_tutorial.jl",
+        "Intro to multi-component models" => "standalone/Usage/LSM_single_column_tutorial.jl",
+        "Intro to ClimaLand Domains" => "standalone/Usage/domain_tutorial.jl",
+        "Intro to forced site-level runs" => "shared_utilities/driver_tutorial.jl",
+    ],
+]

docs/make.jl

@@ -6,40 +6,8 @@ using Distributed
 @everywhere using Literate
 using ClimaLand
 include("pages_helper.jl")
-tutorials = [
-    "For model developers" => [
-        "Intro to standalone models" => "standalone/Usage/model_tutorial.jl",
-        "Intro to multi-component models" => "standalone/Usage/LSM_single_column_tutorial.jl",
-        "Intro to ClimaLand Domains" => "standalone/Usage/domain_tutorial.jl",
-        "Intro to forced site-level runs" => "shared_utilities/driver_tutorial.jl",
-    ],
-    "Running simulations" => [
-        "Bucket LSM" => [
-            "standalone/Bucket/bucket_tutorial.jl",
-            "standalone/Bucket/coupled_bucket.jl",
-        ],
-        "Soil modeling" => [
-            "Boundary conditions" => "standalone/Soil/boundary_conditions.jl",
-            "Richards Equation" => "standalone/Soil/richards_equation.jl",
-            "Energy and Hydrology" => "standalone/Soil/soil_energy_hydrology.jl",
-            "Phase Changes" => "standalone/Soil/freezing_front.jl",
-            "Layered Soil" => "standalone/Soil/layered_soil.jl",
-            "Coarse Sand Evaporation" => "standalone/Soil/evaporation.jl",
-            "Gilat Loess Evaporation" => "standalone/Soil/evaporation_gilat_loess.jl",
-            "Bare soil site" => "standalone/Soil/sublimation.jl",
-        ],
-        "Canopy modeling" => [
-            "Standalone Canopy" => "standalone/Canopy/canopy_tutorial.jl",
-        ],
-        "Integrated soil+canopy modeling" => [
-            "Coupled Canopy and Soil" => "integrated/soil_canopy_tutorial.jl",
-        ],
-        "Snow Modeling" => [
-            "standalone/Snow/base_tutorial.jl",
-            "standalone/Snow/data_tutorial.jl",
-        ],
-    ],
-]
+include("list_tutorials.jl")
+
 @everywhere const clima_dir = dirname(dirname(pathof(ClimaLand)));
 @everywhere source_dir = joinpath(@__DIR__, "src")
 @everywhere GENERATED_DIR = joinpath(source_dir, "generated") # generated files directory
@@ -83,16 +51,15 @@ include("list_standalone_models.jl")
 include("list_diagnostics.jl")
 pages = Any[
     "Home" => "index.md",
-    "APIs" => apis,
-    "Contribution guide" => "Contributing.md",
+    "Getting Started" => "getting_started.md",
     "Tutorials" => tutorials,
-    "Repository structure" => "folderstructure.md",
     "Standalone models" => standalone_models,
     "Diagnostics" => diagnostics,
+    "Contribution guide" => "Contributing.md",
+    "Repository structure" => "folderstructure.md",
+    "APIs" => apis,
 ]
 
-
-
 mathengine = MathJax(
     Dict(
         :TeX => Dict(
@@ -102,7 +69,6 @@ mathengine = MathJax(
     ),
 )
 
-
 format = Documenter.HTML(
     prettyurls = !isempty(get(ENV, "CI", "")),
     collapselevel = 1,

docs/src/getting_started.md

@@ -0,0 +1,60 @@
+# Getting Started
+
+## For Users
+
+### Installation
+
+First, download and install Julia by following the instructions at [https://julialang.org/downloads/](https://julialang.org/downloads/).
+Then, you can install the ClimaLand package by doing:
+
+```julia
+julia> ] # Enter Package REPL mode
+Pkg> add ClimaLand # Install ClimaLand
+Pkg> # Go back to Julia REPL mode
+Julia> using ClimaLand
+```
+
+A typical land simulation employs several different parameterizations to model the various land-surface processes. Let's start our journet into ClimaLand by looking at one of those.
+
+### Parameterization
+
+Let's start with a basic example: compute canopy gross photosynthesis (GPP).
+
+```@repl
+using ClimaLand
+@doc ClimaLand.Canopy.compute_GPP
+```
+
+As you can see, our parameterization for GPP is located in the [`Canopy`](@ref ClimaLand.Canopy) Module, and requires four arguments.
+For example, with An = 5 µmol m⁻² s⁻¹, K = 0.5, LAI = 3 m² m⁻², Ω = 0.7, you can compute GPP like below:
+
+```@repl
+import ClimaLand.Canopy as canopy
+canopy.compute_GPP(5.0, 0.5, 3.0, 0.7)
+```
+
+Et voilà!
+
+Note that our package [ParamViz](https://github.com/CliMA/ParamViz.jl) allows interactive visualisation of
+our parameterizations. See examples in the standalone models pages.
+
+### ClimaLand structure
+
+ClimaLand contains multiple modules. They are listed below:
+
+```@repl
+using MethodAnalysis, ClimaLand
+child_modules(ClimaLand)
+```
+
+To explore what modules, functions and types are exported in a particular module, you can use [About.jl](https://github.com/tecosaur/About.jl):
+
+```@repl
+using ClimaLand
+using About
+about(ClimaLand.Soil.Biogeochemistry)
+```
+
+To see the documentation about a particular module, function or type, you can use ? to go in help mode
+in the REPL, or `@doc` as in [Parameterization above](#Parameterization).
+

docs/src/index.md

@@ -1,4 +1,54 @@
-# ClimaLand.jl
+```@eval
+using Pkg
+io = IOBuffer()
+v = Pkg.installed()["ClimaLand"]
+print(io, """
+    # ClimaLand.jl Documentation (v$(v))
+
+    """)
+import Markdown
+Markdown.parse(String(take!(io)))
+```
+
+## Introduction
+
+ClimaLand is the Land model of the Climate Modeling Alliance (CliMA) Earth System Model, which
+also contains other components ([atmosphere](https://github.com/CliMA/ClimaAtmos.jl), [ocean](https://github.com/CliMA/ClimaOcean.jl), [sea-ice](https://github.com/CliMA/ClimaSeaIce.jl)).
+
+ClimaLand can be run coupled (or "online") with these other components via [ClimaCoupler](https://github.com/CliMA/ClimaCoupler.jl),
+or it can be run as a standalone, via prescribed meteorological data ("offline").
+
+ClimaLand library, described in this documentation, is written in the Julia
+programming language. It aims to be fast and have a clear syntax. ClimaLand
+can run on CPU or GPU, it has a modular design, and is flexible in many ways. This documentation will expand on each of these elements.
+
+## Important Links
+
+- [CliMA Homepage](https://clima.caltech.edu/)
+- [CliMA GitHub Organisation](https://github.com/CliMA)
+- [ClimaCoupler](https://github.com/CliMA/ClimaCoupler.jl)
+- [ClimaAnalysis](https://github.com/CliMA/ClimaAnalysis.jl)
+- [Julia Homepage](https://julialang.org)
+
+## Documentation for Users and Developers
+
+ClimaLand has documentation for both users and developers. The documentation for users is aimed at scientists who wants
+to run simulations using ClimaLand, whereas the documentation for developers is aimed at contributors of the ClimaLand
+code library. As such, users can skip reading the docs for developers, and vice-versa.
+
+## Physical units
+
+Note that CliMA, in all its repositories, uses Standard Units, reminded below
+
+| Quantity              | Unit Name | SI Symbol | SI Unit Equivalent  |
+|:----------------------|:----------|:----------|:--------------------|
+| Length                | Meter     | m         | 1 m                 |
+| Mass                  | Kilogram  | kg        | 1 kg                |
+| Time                  | Second    | s         | 1 s                 |
+| Temperature           | Kelvin    | K         | 1 K                 |
+| Amount of Substance   | Mole      | mol       | 1 mol               |
+| Energy                | Joule     | J         | 1 J = 1 N·m         |
+| Power                 | Watt      | W         | 1 W = 1 J/s         |
+| Pressure              | Pascal    | Pa        | 1 Pa = 1 N/m²       |
+| Frequency             | Hertz     | Hz        | 1 Hz = 1 s⁻¹        |
 
-`ClimaLand.jl` is a [Julia](https://julialang.org/) toolkit for land surface
-modeling.