From 85b4f6cfdb66ca211c63fdf74e8d104157648255 Mon Sep 17 00:00:00 2001
From: Charles Kawczynski <kawczynski.charles@gmail.com>
Date: Wed, 2 Nov 2022 14:05:48 -0700
Subject: [PATCH 1/2] Add example to docs

---
 README.md         |  4 +++-
 docs/src/index.md | 29 ++++++++++++++++++++++++++++-
 2 files changed, 31 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 8360ff9e..3a5bdbaf 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,6 @@
 # Thermodynamics.jl
-A package containing a library of moist thermodynamic relations
+
+Thermodynamics.jl provides flexible and performant functions for computing various thermodynamic variables for dry and moist atmospheres.
 
 |||
 |---------------------:|:----------------------------------------------|
@@ -20,3 +21,4 @@ A package containing a library of moist thermodynamic relations
 [codecov-img]: https://codecov.io/gh/CliMA/Thermodynamics.jl/branch/main/graph/badge.svg
 [codecov-url]: https://codecov.io/gh/CliMA/Thermodynamics.jl
 
+See our documentation [here](https://clima.github.io/Thermodynamics.jl/dev/index).
diff --git a/docs/src/index.md b/docs/src/index.md
index daefa0e8..4f587772 100644
--- a/docs/src/index.md
+++ b/docs/src/index.md
@@ -1,4 +1,31 @@
-# How to guide
+# Thermodynamics
+
+## Principal design
+
+This package uses an abstraction that leverages the idea of a thermodynamic state:
+
+ - given two (or more) independent intrinsic thermodynamic properties, we can establish a thermodynamic state and
+ - given a thermodynamic state, we can compute any thermodynamic property
+
+ 
+## Simple example
+
+For our example, we first load packages, and create a set of thermodynamic parameters, using a convenience constructor, offered through [ClimaParams.jl](https://github.com/CliMA/ClimaParams.jl). Then we create a thermodynamic state using density, liquid-ice potential temperature, and total specific humidity. Finally, we compute air temperature from the thermodynamic state.
+
+```@example
+using ClimaParams # needed in environment to load convenience parameter struct wrappers
+import Thermodynamics as TD
+params = TD.Parameters.ThermodynamicsParameters(Float64);
+
+ts = TD.PhaseEquil_ρθq(params, 1.0, 374.0, 0.01);
+T = TD.air_temperature(params, ts)
+```
+
+And that's it. See a full list of different thermodynamic state constructors, in case you want to create a thermodynamic state with different variables, [here](https://clima.github.io/Thermodynamics.jl/dev/API/#Thermodynamic-State-Constructors).
+
+See a full list of quantities that you can compute from a thermodynamic state, see our thermodynamic state-compatible methods [here](https://clima.github.io/Thermodynamics.jl/dev/API/#Thermodynamic-state-methods).
+
+## How to guide
 
 Thermodynamics.jl provides all thermodynamic functions needed for the
 atmosphere and functions shared across model components. The functions are

From 98a80ed29043d7771751fe7367ab44ef31ce3e25 Mon Sep 17 00:00:00 2001
From: Charles Kawczynski <kawczynski.charles@gmail.com>
Date: Fri, 6 Sep 2024 16:05:46 -0400
Subject: [PATCH 2/2] Reviewer comments

---
 README.md         | 10 ++++++++++
 docs/src/index.md |  3 ++-
 2 files changed, 12 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 3a5bdbaf..c3d45179 100644
--- a/README.md
+++ b/README.md
@@ -22,3 +22,13 @@ Thermodynamics.jl provides flexible and performant functions for computing vario
 [codecov-url]: https://codecov.io/gh/CliMA/Thermodynamics.jl
 
 See our documentation [here](https://clima.github.io/Thermodynamics.jl/dev/index).
+
+Thermodynamics is used by several CliMA components, including:
+
+ - [ClimaAtmos](https://github.com/CliMA/ClimaAtmos.jl)
+ - [ClimaLand](https://github.com/CliMA/ClimaLand.jl)
+ - [ClimaOcean](https://github.com/CliMA/ClimaOcean.jl)
+ - [ClimaCoupler](https://github.com/CliMA/ClimaCoupler.jl)
+ - [CloudMicrophyiscs](https://github.com/CliMA/CloudMicrophysics.jl)
+ - [SurfaceFluxes](https://github.com/CliMA/SurfaceFluxes.jl)
+ - [KinematicDriver](https://github.com/CliMA/KinematicDriver.jl)
diff --git a/docs/src/index.md b/docs/src/index.md
index 4f587772..e4f31033 100644
--- a/docs/src/index.md
+++ b/docs/src/index.md
@@ -82,8 +82,9 @@ using the functions, e.g., for the energies in the module, and computing
 the temperature `T` and the liquid and ice specific humidities (`q.liq` and
 `q.ice`) from the internal energy `e_int` by saturation adjustment.
 
-## Usage
+## Dycore pseudo code
 
+Here, we outline how users might use Thermodynamics inside a circulation model.
 Users are encouraged to first establish a thermodynamic state with one of our
 [Thermodynamic State Constructors](@ref). For example, we would construct
 a moist thermodynamic state using