From 9b23a6274a706c34de1cd61b2064d9bc921f5b55 Mon Sep 17 00:00:00 2001
From: Gabriele Bozzola <gbozzola@caltech.edu>
Date: Wed, 6 Sep 2023 14:30:27 -0700
Subject: [PATCH] Add automatically generated list of diagnostics

---
 .gitignore                    |  3 +++
 docs/make.jl                  |  3 +++
 docs/make_diagnostic_table.jl | 23 +++++++++++++++++++++++
 docs/src/diagnostics.md       |  3 ++-
 4 files changed, 31 insertions(+), 1 deletion(-)
 create mode 100644 docs/make_diagnostic_table.jl

diff --git a/.gitignore b/.gitignore
index f1c4fd2abd4..8f3dc90f697 100644
--- a/.gitignore
+++ b/.gitignore
@@ -22,6 +22,9 @@ deps/src/
 docs/build/
 docs/site/
 
+# File generated by make_available_diagnostics.jl
+docs/src/available_diagnostics.md
+
 # File generated by Pkg, the package manager, based on a corresponding Project.toml
 # It records a fixed state of all packages used by the project. As such, it should not be
 # committed for packages, but should be committed for applications that require a static
diff --git a/docs/make.jl b/docs/make.jl
index 30fa9b15cb9..a2d06ebd901 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -8,6 +8,8 @@ disable_logging(Base.CoreLogging.Info) # Hide doctest's `@info` printing
 doctest(ClimaAtmos)
 disable_logging(Base.CoreLogging.BelowMinLevel) # Re-enable all logging
 
+include("make_diagnostic_table.jl")
+
 makedocs(
     CitationBibliography(joinpath(@__DIR__, "bibliography.bib")),
     modules = [ClimaAtmos],
@@ -27,6 +29,7 @@ makedocs(
         "Equations" => "equations.md",
         "EDMF Equations" => "edmf_equations.md",
         "Diagnostics" => "diagnostics.md",
+        "Available Diagnostics" => "available_diagnostics.md",
         "Diagnostic EDMF Equations" => "diagnostic_edmf_equations.md",
         "Gravity Wave Drag Parameterizations" => "gravity_wave.md",
         "Radiative Equilibrium" => "radiative_equilibrium.md",
diff --git a/docs/make_diagnostic_table.jl b/docs/make_diagnostic_table.jl
new file mode 100644
index 00000000000..66922855ed4
--- /dev/null
+++ b/docs/make_diagnostic_table.jl
@@ -0,0 +1,23 @@
+import ClimaAtmos as CA
+
+# Read all the diagnostics we know how to compute, and print them into a
+# markdown table that is later compiled into the docs
+
+open("src/available_diagnostics.md", "w") do file
+
+    write(file, "# Available diagnostics\n\n")
+
+    write(
+        file,
+        "| Short name | Long name | Standard Name | Units | Comments |\n",
+    )
+    write(file, "|---|---|---|---|---|\n")
+
+    for d in values(CA.ALL_DIAGNOSTICS)
+        write(file, "| $(d.short_name) ")
+        write(file, "| $(d.long_name) ")
+        write(file, "| $(d.standard_name) ")
+        write(file, "| $(d.units) ")
+        write(file, "| $(d.comments)|\n")
+    end
+end
diff --git a/docs/src/diagnostics.md b/docs/src/diagnostics.md
index 5929b2c1c64..2209aae97e8 100644
--- a/docs/src/diagnostics.md
+++ b/docs/src/diagnostics.md
@@ -35,7 +35,8 @@ push!(diagnostics, get_daily_max("air_density", "air_temperature"))
 Now `diagnostics` will also contain the instructions to compute the daily
 maximum of `air_density` and `air_temperature`.
 
-**TODO: Add link to table with known diagnostics**
+The diagnostics that are built-in `ClimaAtmos` are collected in [Available
+diagnostics](@ref).
 
 If you are using `ClimaAtmos` with a script-based interface, you have access to
 the complete flexibility in your diagnostics. Read the section about the