Setup doctests

.github/workflows/CI.yml

@@ -27,6 +27,7 @@ jobs:
         run: julia --project=docs/ -e 'using Pkg;
           Pkg.develop(PackageSpec(path=pwd()));
           Pkg.instantiate()'
+      - run: printenv | sort
       - name: Make docs
         run: julia --project=docs/ docs/make.jl
         env:

Project.toml

@@ -9,13 +9,15 @@ Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
 
 [compat]
-julia = "1.0"
 Distributions = "0.23.2"
 StatsBase = "0.33.0"
+julia = "1.0"
 
 [extras]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [targets]
-test = ["Test", "Statistics"]
+test = ["Documenter", "Random", "Statistics", "Test"]

README.md

@@ -18,8 +18,8 @@ Glass's *Δ* | `GlassΔ`
 
 ## Installation
 
-```julia
-] add https://github.com/harryscholes/EffectSizes.jl
+```jl
+julia> import Pkg; Pkg.add("EffectSizes");
 ```
 
 ## Examples
@@ -34,10 +34,10 @@ julia> ys = randn(10^3) .+ 0.5;
 julia> es = CohenD(xs, ys, quantile=0.95); # normal CI (idealised distribution)
 
 julia> typeof(es)
-CohenD{Float64,ConfidenceInterval{Float64}}
+CohenD{Float64, ConfidenceInterval{Float64}}
 
 julia> effectsize(es)
--0.507…
+-0.5477257247459636
 
 julia> quantile(es)
 0.95
@@ -48,23 +48,23 @@ julia> typeof(ci)
 ConfidenceInterval{Float64}
 
 julia> confint(ci)
-(-0.924…, -0.0889…)
+(-0.9660399771191736, -0.12941147237275363)
 
 julia> es = CohenD(xs, ys, 10^4, quantile=0.95); # bootstrap CI (empirical distribution)
 
 julia> effectsize(es) # effect size is the same
--0.507…
+-0.5477257247459636
 
 julia> typeof(es)
-CohenD{Float64,BootstrapConfidenceInterval{Float64}}
+CohenD{Float64, BootstrapConfidenceInterval{Float64}}
 
 julia> ci = confint(es); # confidence interval is different
 
 julia> lower(ci)
--0.597…
+-0.6367371804827419
 
 julia> upper(ci)
--0.418…
+-0.4598929721717412
 ```
 
 ## Contributing

docs/src/README.md

@@ -0,0 +1,3 @@
+# docs/src
+
+This folder is required by Documenter.jl even if we only run doctests.

src/EffectSizes.jl

@@ -1,10 +1,12 @@
-"""
-    EffectSizes
-
-A Julia package for effect size measures.
-"""
 module EffectSizes
 
+using Statistics
+using Distributions
+using StatsBase
+
+import Distributions: quantile
+import StatsBase: confint
+
 export
     AbstractEffectSize,
     EffectSize,
@@ -20,13 +22,20 @@ export
     lower,
     upper
 
+"""
+    _update_module_doc()
 
-using Statistics
-using Distributions
-using StatsBase
-
-import Distributions: quantile
-import StatsBase: confint
+This function updates the module docs and is called before running the doctests.
+This way, the docs in README.md are also tested.
+"""
+function _update_module_doc()
+    path = joinpath(@__DIR__, "..", "README.md")
+    text = read(path, String)
+    # The code blocks in the README.md should be julia blocks the syntax highlighter.
+    text = replace(text, "```julia" => "```jldoctest")
+    @doc text EffectSizes
+end
+_update_module_doc()
 
 include("confidence_interval.jl")
 include("effect_size.jl")

test/runtests.jl

@@ -1,6 +1,22 @@
+using Documenter
 using EffectSizes
 using Test
 
+DocMeta.setdocmeta!(
+    EffectSizes,
+    :DocTestSetup,
+    :(using EffectSizes);
+    recursive=true
+)
+
+# Only test one Julia version to avoid differences due to changes in printing.
+if v"1.6" ≤ VERSION
+    EffectSizes._update_module_doc()
+    doctest(EffectSizes)
+else
+    @warn "Skipping doctests"
+end
+
 @testset "EffectSizes.jl" begin
     include("test_confint.jl")
     include("test_effectsize.jl")