literate density_from_temperature_pressure_humidity.jl + add to docs

docs/Project.toml

@@ -1,10 +1,13 @@
 [deps]
+CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
 ClimaParams = "5c42b081-d73a-476f-9059-fd94b934656c"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
 ExprTools = "e2ba6199-217a-4e67-a87a-7c52f15ade04"
 ForwardDiff = "f6369f11-7733-5829-9624-2563aa707210"
+JLD2 = "033835bb-8acc-5ee8-8aae-3f567f8a3819"
 KernelAbstractions = "63c18a36-062a-441e-b654-da1e3ab1ce7c"
+Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
 RootSolvers = "7181ea78-2dcb-4de3-ab41-2b8ab5a31e74"
 Thermodynamics = "b60c26fb-14c3-4610-9d3e-2d17fe7ff00c"

docs/make.jl

@@ -1,16 +1,48 @@
-using Thermodynamics, Documenter
-using DocumenterCitations
+using Thermodynamics
+using Documenter, DocumenterCitations, Literate, Printf
 
 # https://github.com/jheinen/GR.jl/issues/278#issuecomment-587090846
 ENV["GKSwstype"] = "nul"
 
+const EXAMPLES_DIR = joinpath(@__DIR__, "..", "examples")
+const OUTPUT_DIR   = joinpath(@__DIR__, "src/literated")
+
 bib = CitationBibliography(joinpath(@__DIR__, "bibliography.bib"))
 
+example_scripts = [
+    "density_from_temperature_pressure_humidity.jl",
+]
+
+const EXAMPLES_DIR = joinpath(@__DIR__, "..", "examples")
+const OUTPUT_DIR   = joinpath(@__DIR__, "src/literated")
+
+if isdir(OUTPUT_DIR); rm(OUTPUT_DIR); end
+mkdir(OUTPUT_DIR)
+cp(joinpath(EXAMPLES_DIR, "JRA55_atmospheric_state_Jan_1_1991.jld2"), joinpath(OUTPUT_DIR, "JRA55_atmospheric_state_Jan_1_1991.jld2"))
+
+for example in example_scripts
+    example_filepath = joinpath(EXAMPLES_DIR, example)
+
+    withenv("JULIA_DEBUG" => "Literate") do
+        start_time = time_ns()
+        Literate.markdown(example_filepath, OUTPUT_DIR;
+                          flavor = Literate.DocumenterFlavor(),
+                          execute = true)
+        elapsed = 1e-9 * (time_ns() - start_time)
+        @info @sprintf("%s example took %s seconds to build.", example, elapsed)
+    end
+end
+
+example_pages = [
+    "Density from temperature, pressure, and humidity" => "literated/density_from_temperature_pressure_humidity.md",
+]
+
 pages = Any[
     "Home" => "index.md",
     "Installation" => "Installation.md",
     "API" => "API.md",
     "How-to-guide" => "HowToGuide.md",
+    "Examples" => example_pages,
     "Tested profiles" => "TestedProfiles.md",
     "Temperature profiles" => "TemperatureProfiles.md",
     "Developer docs" => "DevDocs.md",
@@ -32,6 +64,7 @@ format = Documenter.HTML(
     prettyurls = get(ENV, "CI", nothing) == "true",
     mathengine = mathengine,
     collapselevel = 1,
+    size_threshold = 819200,
 )
 
 makedocs(;
@@ -45,6 +78,27 @@ makedocs(;
     pages = pages,
 )
 
+@info "Clean up temporary .jld2 and .nc output created by doctests or literated examples..."
+
+"""
+    recursive_find(directory, pattern)
+
+Return list of filepaths within `directory` that contains the `pattern::Regex`.
+"""
+recursive_find(directory, pattern) =
+    mapreduce(vcat, walkdir(directory)) do (root, dirs, files)
+        joinpath.(root, filter(contains(pattern), files))
+    end
+
+files = []
+for pattern in [r"\.jld2", r"\.nc"]
+    global files = vcat(files, recursive_find(@__DIR__, pattern))
+end
+
+for file in files
+    rm(file)
+end
+
 deploydocs(
     repo = "github.com/CliMA/Thermodynamics.jl.git",
     target = "build",

examples/density_from_temperature_pressure_humidity.jl

@@ -1,4 +1,4 @@
-#! format: off
+#! format: off #src
 
 # # Defining a simple parameter set and using it to compute density
 #
@@ -26,21 +26,16 @@ end
                                water_molar_mass   = 0.018015)
 
 Construct a set of parameters that define the density of moist air,
-
 ```math
 ρ = p / Rᵐ(q) T,
 ```
-
 where ``p`` is pressure, ``T`` is temperature, ``q`` defines the partition
 of total mass into vapor, liqiud, and ice mass fractions, and
 ``Rᵐ`` is the effective specific gas constant for the mixture,
-
 ```math
 Rᵐ(q) = 
 ```
-
 where 
-
 For more information see [reference docs].
 """
 function ConstitutiveParameters(
@@ -115,12 +110,11 @@ using JLD2
 # variables substampled from the JRA55 dataset, from the date Jan 1, 1991:
 
 @load "JRA55_atmospheric_state_Jan_1_1991.jld2" q T p
-nothing
 
-# The variables q, T and p correspond to the total specific humidity (a mass fraction),
-# temperature (Kelvin), and sea level pressure (Pa)
+# The variables `q`, `T`, and `p` correspond to the total specific humidity
+# (a mass fraction), temperature (Kelvin), and sea level pressure (Pa)
 #
-# We use q to build a vector of PhasePartition,
+# We use `q` to build a vector of PhasePartition,
 
 qp = PhasePartition.(q)
 
@@ -144,7 +138,7 @@ Tmax = maximum(T)
 Trange = (Tmin, Tmax)
 Tmap = :viridis
 
-fig = Figure(size = (1200, 500))
+fig = Figure(size = (1000, 450))
 
 axρ = Axis(fig[2, 1], xlabel = "Temperature (K) ", ylabel = "Density (kg m⁻³)")
 axq = Axis(fig[2, 2], xlabel = "Specific humidity", ylabel = "Density (kg m⁻³)")
@@ -155,8 +149,6 @@ scatter!(axq, q[:], ρ[:], color = T[:], colorrange = Trange, colormap = Tmap, a
 Colorbar(fig[1, 1], label = "Pressure (Pa)", vertical = false, colorrange = prange, colormap = pmap)
 Colorbar(fig[1, 2], label = "Temperature (K)", vertical = false, colorrange = Trange, colormap = Tmap)
 
-save(fig, "density_versus_temperature.png")
-
 current_figure()
 
-#! format: on
+#! format: on #src