Merge pull request #334 from FourierFlows/ncc/add-documenter-citations

Add references in the Docs via DocumenterCitations.jl
FourierFlows · Oct 27, 2023 · 54140de · 54140de
2 parents 700fd74 + 67f109d
commit 54140de
Show file tree

Hide file tree

Showing 10 changed files with 105 additions and 20 deletions.
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -2,6 +2,7 @@
 CUDA = "052768ef-5323-5732-b1bb-66c8b64840ba"
 CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
 JLD2 = "033835bb-8acc-5ee8-8aae-3f567f8a3819"
 Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
 Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
@@ -10,4 +11,5 @@ Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
 CUDA = "1, 2.4.2, 3.0.0 - 3.6.4, 3.7.1, 4"
 CairoMakie = "< 0.10.5"
 Documenter = "1"
+DocumenterCitations = "1.2"
 Literate = "≥2.9.0"
diff --git a/docs/make.jl b/docs/make.jl
@@ -1,4 +1,4 @@
-using Documenter, Literate
+using Documenter, DocumenterCitations, Literate
 
 using CairoMakie
 # CairoMakie.activate!(type = "svg")
@@ -47,14 +47,18 @@ format = Documenter.HTML(
       canonical = "https://fourierflows.github.io/GeophysicalFlowsDocumentation/stable/"
 )
 
+bib_filepath = joinpath(dirname(@__FILE__), "src/references.bib")
+bib = CitationBibliography(bib_filepath, style=:authoryear)
+
 makedocs(
+  authors = "Navid C. Constantinou, Gregory L. Wagner, and contributors",
+ sitename = "GeophysicalFlows.jl",
   modules = [GeophysicalFlows],
+  plugins = [bib],
+   format = format,
   doctest = true,
     clean = true,
 checkdocs = :all,
-   format = format,
-  authors = "Navid C. Constantinou, Gregory L. Wagner, and contributors",
- sitename = "GeophysicalFlows.jl",
     pages = Any[
                 "Home" => "index.md",
                 "Installation instructions" => "installation_instructions.md",
@@ -92,6 +96,7 @@ checkdocs = :all,
                   ],
                 "Stochastic forcing" => "stochastic_forcing.md",
                 "Contributor's guide" => "contributing.md",
+                "References" => "references.md",
                 "Library" => Any[
                   "lib/types.md",
                   "lib/functions.md"

diff --git a/docs/src/modules/barotropicqgql.md b/docs/src/modules/barotropicqgql.md
@@ -11,11 +11,7 @@ e.g.,
 \phi(x, y, t) = \overline{\phi}(y, t) + \phi'(x, y, t) ,
 ```
 
-where overline above denotes a zonal mean, ``\overline{\phi}(y, t) = \int \phi(x, y, t) \, 𝖽x / L_x``, and prime denotes deviations from the zonal mean. This approximation is used in many process-model studies of zonation, e.g., 
-
-- Farrell, B. F. and Ioannou, P. J. (2003). [Structural stability of turbulent jets.](http://doi.org/10.1175/1520-0469(2003)060<2101:SSOTJ>2.0.CO;2) *J. Atmos. Sci.*, **60**, 2101-2118.
-- Srinivasan, K. and Young, W. R. (2012). [Zonostrophic instability.](http://doi.org/10.1175/JAS-D-11-0200.1) *J. Atmos. Sci.*, **69 (5)**, 1633-1656.
-- Constantinou, N. C., Farrell, B. F., and Ioannou, P. J. (2014). [Emergence and equilibration of jets in beta-plane turbulence: applications of Stochastic Structural Stability Theory.](http://doi.org/10.1175/JAS-D-13-076.1) *J. Atmos. Sci.*, **71 (5)**, 1818-1842.
+where overline above denotes a zonal mean, ``\overline{\phi}(y, t) = \int \phi(x, y, t) \, 𝖽x / L_x``, and prime denotes deviations from the zonal mean. This approximation is used in many process-model studies of zonation, e.g., [Farrell-Ioannou-2003](@citet), [Srinivasan-Young-2012](@citet), and [Constantinou-etal-2014](@citet).
 
 As in the [SingleLayerQG module](singlelayerqg.md), the flow is obtained through a 
 streamfunction ``\psi`` as ``(u, v) = (-\partial_y \psi, \partial_x \psi)``. All flow fields 

diff --git a/docs/src/modules/surfaceqg.md b/docs/src/modules/surfaceqg.md
@@ -3,7 +3,7 @@
 ### Basic Equations
 
 This module solves the non-dimensional surface quasi-geostrophic (SQG) equation for surface 
-buoyancy ``b_s = b(x, y, z=0)``, as described in Capet et al., 2008. The buoyancy and the fluid 
+buoyancy ``b_s = b(x, y, z=0)``, as described by [Capet-etal-2008](@citet). The buoyancy and the fluid 
 velocity at the surface are related through a streamfunction ``\psi`` via:
 
 ```math
@@ -101,5 +101,3 @@ Other diagnostic include: [`buoyancy_dissipation`](@ref GeophysicalFlows.Surface
 
 - [`examples/surfaceqg_decaying.jl`](@ref surfaceqg_decaying_example): Simulate decaying surface quasi-geostrophic flow 
   with a prescribed initial buoyancy field.
-
-  > Capet, X. et al., (2008). Surface kinetic energy transfer in surface quasi-geostrophic flows. *J. Fluid Mech.*, **604**, 165-174.
diff --git a/docs/src/modules/twodnavierstokes.md b/docs/src/modules/twodnavierstokes.md
@@ -94,8 +94,6 @@ Other diagnostic include: [`energy_dissipation`](@ref GeophysicalFlows.TwoDNavie
 - [`examples/twodnavierstokes_decaying.jl`](@ref twodnavierstokes_decaying_example): Simulates decaying two-dimensional
   turbulence reproducing the results by:
 
-  > McWilliams, J. C. (1984). The emergence of isolated coherent vortices in turbulent flow. *J. Fluid Mech.*, **146**, 21-43.
-
 - [`examples/twodnavierstokes_stochasticforcing.jl`](@ref twodnavierstokes_stochasticforcing_example): Simulate forced-dissipative
   two-dimensional turbulence with isotropic temporally delta-correlated stochastic forcing.
 

diff --git a/docs/src/references.bib b/docs/src/references.bib
@@ -0,0 +1,81 @@
+@article{Held-etal-1995,
+  title={Surface quasi-geostrophic dynamics},
+  author={Held, Isaac M. and Pierrehumbert, Raymond T. and Garner, Stephen T. and Swanson, Kyle L.},
+  journal={Journal of Fluid Mechanics},
+  volume={282},
+  pages={1--20},
+  year={1995},
+  doi={10.1017/S0022112095000012}
+}
+
+@article{Capet-etal-2008,
+  title={Surface kinetic energy transfer in surface quasi-geostrophic flows},
+  author={Capet, Xavier and Klein, Patrice and Hua, Bach Lien and Lapeyre, Guillaume and Mcwilliams, James C.},
+  journal={Journal of Fluid Mechanics},
+  volume={604},
+  pages={165--174},
+  year={2008},
+  doi={10.1017/S0022112008001110}
+}
+
+@article{McWilliams-1984,
+  title={The emergence of isolated coherent vortices in turbulent flow},
+  author={Mcwilliams, James C.},
+  journal={Journal of Fluid Mechanics},
+  volume={146},
+  pages={21--43},
+  year={1984},
+  doi={10.1017/S0022112084001750}
+}
+
+@article{Farrell-Ioannou-2003,
+  title = {Structural stability of turbulent jets},
+  author = {Farrell, Brian F. and Ioannou, Petros J.},
+  journal = {Journal of the Atmospheric Sciences},
+  pages = {2101--2118},
+  volume = 60,
+  year = 2003,
+  doi = {10.1175/1520-0469(2003)060<2101:SSOTJ>2.0.CO;2},
+}
+
+@article{Constantinou-etal-2014,
+  title = {Emergence and equilibration of jets in beta-plane turbulence: applications of Stochastic Structural Stability Theory},
+  author = {Constantinou, Navid C. and Farrell, Brian F. and Ioannou, Petros J.},
+  journal = {Journal of the Atmospheric Sciences},
+  volume = {71},
+  number = {5},
+  pages = {1818--1842},
+  year = {2014},
+  doi = {10.1175/JAS-D-13-076.1},
+}
+
+@article{Srinivasan-Young-2012,
+  title = {Zonostrophic instability},
+  author = {Srinivasan, Kaushik and Young, William R.},
+  journal = {Journal of the Atmospheric Sciences},
+  volume = {69},
+  number = {5},
+  pages = {1633--1656},
+  year = {2012},
+  doi = {10.1175/JAS-D-11-0200.1},
+}
+
+@article{vanKampen-1981,
+  title={Itô versus Stratonovich},
+  author={Van Kampen, Nicolaas G},
+  journal={Journal of Statistical Physics},
+  volume={24},
+  pages={175--187},
+  year={1981},
+  doi={10.1007/BF01007642}
+}
+
+@phdthesis{Constantinou-2015-phd,
+  title = {Formation of large-scale structures by turbulence in rotating planets},
+  author = {Constantinou, N. C.},
+  school = {National and Kapodistrian University of Athens},
+  address = {Athens},
+  url = {http://www.didaktorika.gr/eadd/handle/10442/35501?locale=en},
+  year = {2015},
+  note = {(also available at arXiv:1503.07644)}
+}
diff --git a/docs/src/references.md b/docs/src/references.md
@@ -0,0 +1,4 @@
+# References
+
+```@bibliography
+```
diff --git a/docs/src/stochastic_forcing.md b/docs/src/stochastic_forcing.md
@@ -141,7 +141,7 @@ the other hand, the chain rule in Stratonovich calculus coincides with that in n
 This stems from the fact that in the Stratonovich interpretation the white noise process is as 
 a series of colored noise processes with the de-correlation time tending to zero. This made 
 Stratonovich calculus more popular in the physics community. A nice discussion on the differences 
-and similarities between the two calculi is given by [van Kampen](https://doi.org/10.1007/BF01007642).
+and similarities between the two calculi is given by [vanKampen-1981](@citet).
 
 ## A simple Stochastic Differential Equation: the Ornstein--Uhlenbeck process
 
@@ -158,7 +158,7 @@ Note that in differential form (1) is written as:
 ```
 
 Luckily, for (2) we don't need to distinguish between Itô and Stratonovich, since ``g`` is 
-independent of ``x(t)``. But note that oftentimes this is not the case; that ``g`` is independent 
+independent of ``x(t)``. But note that often this is not the case; that ``g`` is independent 
 of ``x(t)`` is only a fortuitous coincident for this particular SDE.
 
 How do we time-step SDE (2) numerically? Let us assume a discretization of time into time-steps
@@ -456,7 +456,7 @@ The forcing ``\xi`` obeys:
 
 that is, the forcing is white in time but spatially correlated; its spatial correlation is 
 prescribed by the function ``Q`` which is, necessarily, homogeneous in all its arguments
-(see discussion by [Constantinou (2015)](http://arxiv.org/abs/1503.07644); Appendix A).
+(see discussion by [Constantinou-2015-phd](@citet); Appendix A).
 
 Equation (6) above describes the vorticity evolution of a two-dimensional fluid ``\nabla^2 \psi`` 
 that is stochastically forced while dissipated by linear drag ``\mu``. The energy of the 

diff --git a/examples/surfaceqg_decaying.jl b/examples/surfaceqg_decaying.jl
@@ -2,7 +2,7 @@
 #
 # A simulation of decaying surface quasi-geostrophic turbulence.
 # We reproduce here the initial value problem for an elliptical 
-# vortex as done by Held et al. 1995, _J. Fluid Mech_.
+# vortex as done by [Held-etal-1995](@citet).
 # 
 # An example of decaying barotropic quasi-geostrophic turbulence over topography.
 #

diff --git a/examples/twodnavierstokes_decaying.jl b/examples/twodnavierstokes_decaying.jl
@@ -1,6 +1,7 @@
 # # [2D decaying turbulence](@id twodnavierstokes_decaying_example)
 #
-# A simulation of decaying two-dimensional turbulence.
+# A simulation of decaying two-dimensional turbulence closely following
+# the paper by [McWilliams-1984](@citet).
 # 
 # ## Install dependencies
 #
@@ -58,7 +59,7 @@ nothing #hide
 
 # ## Setting initial conditions
 
-# Our initial condition tries to reproduce the initial condition used by McWilliams (_JFM_, 1984).
+# Our initial condition tries to reproduce the initial condition used by [McWilliams-1984](@citet).
 seed!(1234)
 k₀, E₀ = 6, 0.5
 ζ₀ = peakedisotropicspectrum(grid, k₀, E₀, mask=prob.timestepper.filter)