From 82b2faf8707c715e920263836b864ca1e19d5011 Mon Sep 17 00:00:00 2001
From: Gabriele Bozzola <gbozzola@caltech.edu>
Date: Thu, 14 Dec 2023 11:05:29 -0800
Subject: [PATCH] Add doctest

---
 Project.toml     |  4 +++-
 src/OutputVar.jl | 29 ++++++++++++++++++++---------
 src/Utils.jl     | 42 +++++++++++++++++++++---------------------
 test/doctest.jl  | 14 ++++++++++++++
 test/runtests.jl |  2 ++
 5 files changed, 60 insertions(+), 31 deletions(-)
 create mode 100644 test/doctest.jl

diff --git a/Project.toml b/Project.toml
index de641c3b..b0be0d6e 100644
--- a/Project.toml
+++ b/Project.toml
@@ -17,6 +17,7 @@ CairoMakieExt = "CairoMakie"
 [compat]
 Aqua = "0.8"
 CairoMakie = "0.9, 0.10, 0.11"
+Documenter = "1"
 JuliaFormatter = "1"
 NCDatasets = "0.12, 0.13"
 OrderedCollections = "1"
@@ -28,9 +29,10 @@ julia = "1.9"
 [extras]
 Aqua = "4c88cf16-eb10-579e-8560-4a9242c79595"
 CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 JuliaFormatter = "98e50ef6-434e-11e9-1051-2b60c6c9e899"
 SafeTestsets = "1bc83da4-3b8d-516f-aca4-4fe02f6d838f"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [targets]
-test = ["Aqua", "CairoMakie", "JuliaFormatter", "SafeTestsets", "Test"]
+test = ["Aqua", "CairoMakie", "Documenter", "JuliaFormatter", "SafeTestsets", "Test"]
diff --git a/src/OutputVar.jl b/src/OutputVar.jl
index 0a2a4d10..73eb9322 100644
--- a/src/OutputVar.jl
+++ b/src/OutputVar.jl
@@ -3,6 +3,18 @@ import OrderedCollections: OrderedDict
 
 import Statistics: mean
 
+export OutputVar,
+    read_var,
+    average_lat,
+    average_lon,
+    average_time,
+    slice_time,
+    slice_x,
+    slice_x,
+    slice_y,
+    slice_lon,
+    slice_lat
+
 struct OutputVar{
     T <: AbstractArray,
     A <: AbstractArray,
@@ -105,15 +117,14 @@ Example
 
 Average over latitudes
 
-```jldoctest
-julia> import Statistics: mean
-julia> long = 0.:180. |> collect
-julia> lat = 0.:90. |> collect
-julia> data = reshape(1.:91*181., (181, 91))
-julia> dims = Dict(["lat" => lat, "long" => long])
-julia> var = OutputVar(dims, data)
-
-julia> reduce_over(mean, "lat", var)
+```julia
+import Statistics: mean
+long = 0.:180. |> collect
+lat = 0.:90. |> collect
+data = reshape(1.:91*181., (181, 91))
+dims = Dict(["lat" => lat, "long" => long])
+var = OutputVar(dims, data)
+_reduce_over(mean, "lat", var)
 ```
 """
 function _reduce_over(
diff --git a/src/Utils.jl b/src/Utils.jl
index 1ab3f6fc..271b9da5 100644
--- a/src/Utils.jl
+++ b/src/Utils.jl
@@ -1,5 +1,7 @@
 module Utils
 
+export match_nc_filename, squeeze, nearest_index, kwargs
+
 """
     match_nc_filename(filename::String)
 
@@ -11,32 +13,23 @@ The convention is: `shortname_(period)_reduction.nc`, with `period` being option
 Examples
 =========
 
-```julia-repl
+```jldoctest
 julia> match_nc_filename("bob")
 ```
 
-```julia-repl
+```jldoctest
 julia> match_nc_filename("ta_1d_average.nc")
-3-element Vector{Union{Nothing, SubString{String}}}:
- "ta"
- "1d"
- "average"
+("ta", "1d", "average")
 ```
 
-```julia-repl
+```jldoctest
 julia> match_nc_filename("pfull_6.0min_max.nc")
-3-element Vector{Union{Nothing, SubString{String}}}:
- "pfull"
- "6.0min"
- "max"
+("pfull", "6.0min", "max")
 ```
 
-```julia-repl
+```jldoctest
 julia> match_nc_filename("hu_inst.nc")
-3-element Vector{Union{Nothing, SubString{String}}}:
- "hu"
- nothing
- "inst"
+("hu", nothing, "inst")
 ```
 """
 function match_nc_filename(filename::String)
@@ -78,13 +71,18 @@ Examples
 =========
 
 ```jldoctest
-julia> A = [[1 2] [3 4]]
+julia> A = [[1 2] [3 4]];
+
 julia> size(A)
 (1, 4)
-julia> A_squeezed = squeeze(A)
+
+julia> A_squeezed = squeeze(A);
+
 julia> size(A_squeezed)
-(4, )
-julia> A_not_squeezed = squeeze(A; dims = (2, ))
+(4,)
+
+julia> A_not_squeezed = squeeze(A; dims = (2, ));
+
 julia> size(A_not_squeezed)
 (1, 4)
 ```
@@ -116,9 +114,11 @@ Examples
 =========
 
 ```jldoctest
-julia> A = [-1, 0, 1, 2, 3, 4, 5]
+julia> A = [-1, 0, 1, 2, 3, 4, 5];
+
 julia> nearest_index(A, 3)
 5
+
 julia> nearest_index(A, 0.1)
 2
 ```
diff --git a/test/doctest.jl b/test/doctest.jl
new file mode 100644
index 00000000..194b54f1
--- /dev/null
+++ b/test/doctest.jl
@@ -0,0 +1,14 @@
+using Documenter
+import ClimaAnalysis
+
+@testset "Test docstrings" begin
+
+    DocMeta.setdocmeta!(
+        ClimaAnalysis,
+        :DocTestSetup,
+        :(using ClimaAnalysis.Utils);
+        recursive = true,
+    )
+
+    doctest(ClimaAnalysis; manual = false)
+end
diff --git a/test/runtests.jl b/test/runtests.jl
index d353d69d..cf14e4c1 100644
--- a/test/runtests.jl
+++ b/test/runtests.jl
@@ -3,7 +3,9 @@ using Test
 
 #! format: off
 @safetestset "Aqua" begin @time include("aqua.jl") end
+@safetestset "Docstrings" begin @time include("doctest.jl") end
 @safetestset "Format" begin @time include("format.jl") end
+
 @safetestset "Utils" begin @time include("Utils.jl") end
 @safetestset "SimDir" begin @time include("SimDir.jl") end
 @safetestset "OutputVar" begin @time include("OutputVar.jl") end