Use DocumenterCitations for proper citing in docs (#530)

* use DocumenterCitations for proper citing in docs

* trigger docs built

Author: navidcy

docs/Project.toml

@@ -3,6 +3,7 @@ CFTime = "179af706-886a-5703-950a-314cd64e0468"
 CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
 DataDeps = "124859b0-ceae-595e-8997-d05f6a7a8dfe"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
 Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
 Oceananigans = "9e8cae18-63c1-5223-a75c-80ca9d6e9a09"
 SeawaterPolynomials = "d496a93d-167e-4197-9f49-d3af4ff8fe40"
@@ -11,5 +12,6 @@ SeawaterPolynomials = "d496a93d-167e-4197-9f49-d3af4ff8fe40"
 CairoMakie = "0.10.12, 0.11, 0.12, 0.13"
 DataDeps = "0.7"
 Documenter = "1"
+DocumenterCitations = "1.3"
 Oceananigans = "0.96 - 0.99"
 SeawaterPolynomials = "0.3.5"

docs/climaocean.bib

@@ -0,0 +1,10 @@
+@article{edson2013exchange,
+  title={On the exchange of momentum over the open ocean},
+  author={Edson, James B and Jampana, Venkata and Weller, Robert A and Bigorre, Sebastien P and Plueddemann, Albert J and Fairall, Christopher W and Miller, Scott D and Mahrt, Larry and Vickers, Dean and Hersbach, Hans},
+  journal={Journal of Physical Oceanography},
+  volume={43},
+  number={8},
+  pages={1589--1610},
+  year={2013},
+  doi={10.1175/JPO-D-12-0173.1}
+}

docs/make.jl

@@ -1,10 +1,14 @@
 using
   ClimaOcean,
   Documenter,
+  DocumenterCitations,
   Literate
 
 ENV["DATADEPS_ALWAYS_ACCEPT"] = "true"
 
+bib_filepath = joinpath(dirname(@__FILE__), "climaocean.bib")
+bib = CitationBibliography(bib_filepath, style=:authoryear)
+
 #####
 ##### Generate examples
 #####
@@ -57,11 +61,13 @@ pages = [
         "Private"        => "library/internals.md",
         "Function index" => "library/function_index.md",
         ],
+    "References" => "references.md",
 ]
 
 makedocs(sitename = "ClimaOcean.jl";
          format,
          pages,
+         plugins = [bib],
          modules = [ClimaOcean],
          doctest = true,
          clean = true,

docs/src/references.md

@@ -0,0 +1,4 @@
+# References
+
+```@bibliography
+```

src/OceanSeaIceModels/InterfaceComputations/roughness_lengths.jl

@@ -145,7 +145,7 @@ end
 @inline roughness_length(ℓ::Number, args...) = ℓ
 
 # Momentum roughness length should be different from scalar roughness length.
-# Temperature and water vapor can be considered the same (Edson et al 2013)
+# Temperature and water vapor can be considered the same (Edson et al. 2013)
 @inline function roughness_length(ℓ::MomentumRoughnessLength{FT}, ΔU, u★, 𝒬, ℂ) where FT
     g  = ℓ.gravitational_acceleration
     β  = ℓ.laminar_parameter
@@ -171,11 +171,13 @@ end
 """
     ReynoldsScalingFunction(FT=Float64; A=5.85e-5, b=0.72)
 
-Empirical fit of the scalar roughness length with roughness Reynolds number `R★ = u★ ℓu / ν`.
-Edson et al. (2013), equation (28).
+Empirical fit of the scalar roughness length with roughness Reynolds number `R★ = u★ ℓu / ν`
+
 ```math
     ℓs = A / R★ ^ b
 ```
+
+See equation (28) by [edson2013exchange](@citet).
 """
 ReynoldsScalingFunction(FT = Oceananigans.defaults.FloatType; A = 5.85e-5, b = 0.72) =
     ReynoldsScalingFunction(convert(FT, A), convert(FT, b))

src/OceanSeaIceModels/InterfaceComputations/similarity_theory_turbulent_fluxes.jl

@@ -78,9 +78,9 @@ Keyword Arguments
 - `turbulent_prandtl_number`: The turbulent Prandtl number. Default: 1.
 - `gustiness_parameter`: Increases surface fluxes in low wind conditions. Default: 1.
 - `stability_functions`: The stability functions. Default: `default_stability_functions(FT)` that follow the
-                         formulation of Edson et al. (2013).
+                         formulation of [edson2013exchange](@citet).
 - `roughness_lengths`: The roughness lengths used to calculate the characteristic scales for momentum, temperature and
-                       water vapor. Default: `default_roughness_lengths(FT)`, formulation taken from Edson et al (2013).
+                       water vapor. Default: `default_roughness_lengths(FT)`, formulation taken from [edson2013exchange](@citet).
 - `similarity_form`: The type of similarity profile used to relate the atmospheric state to the
                              interface fluxes / characteristic scales.
 - `solver_tolerance`: The tolerance for convergence. Default: 1e-8.
@@ -181,7 +181,7 @@ function iterate_interface_fluxes(flux_formulation::SimilarityTheoryFluxes,
     L★ = ifelse(b★ == 0, Inf, - u★^2 / (ϰ * b★))
 
 
-    # Buoyancy flux characteristic scale for gustiness (Edson 2013)
+    # Buoyancy flux characteristic scale for gustiness (Edson et al. 2013)
     h_bℓ = atmosphere_state.h_bℓ
     Jᵇ = - u★ * b★
     Uᴳ = β * cbrt(Jᵇ * h_bℓ)
@@ -269,7 +269,7 @@ end
 """
     EdsonMomentumStabilityFunction{FT}
 
-A struct representing the momentum stability function detailed in Edson et al (2013).
+A struct representing the momentum stability function detailed in paper by [edson2013exchange](@citet).
 The formulation hinges on the definition of three different functions:
 one for stable atmospheric conditions ``(ζ > 0)``, named ``ψₛ`` and two for unstable conditions,
 named ``ψᵤ₁`` and ``ψᵤ₂``.
@@ -348,7 +348,7 @@ end
 """
     EdsonScalarStabilityFunction{FT}
 
-A struct representing the scalar stability function detailed in Edson et al (2013).
+A struct representing the scalar stability function detailed by [edson2013exchange](@citet).
 The formulation hinges on the definition of three different functions:
 one for stable atmospheric conditions ``(ζ > 0)``, named ``ψₛ`` and two for unstable conditions,
 named ``ψᵤ₁`` and ``ψᵤ₂``.