Use Doctests

docs/Project.toml

@@ -1,5 +1,9 @@
 [deps]
+Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Mimi = "e4e893b0-ee5e-52ea-8111-44b3bdec128c"
 
 [compat]
+Distributions = "0.21"
 Documenter = "~0.21"
+Mimi = "0.9.3"

docs/src/faq.md

@@ -1,5 +1,11 @@
 # Frequently asked questions
 
+```@meta
+DocTestSeup =
+    using Mimi
+    using Distributions
+end
+```
 ## What's up with the name?
 
 The name is probably an acronym for "Modular Integrated Modeling Interface", but we are not sure. What is certain is that it came up during a dinner that [Bob](http://www.bobkopp.net/), [David](http://www.david-anthoff.com/) and [Sol](http://www.solomonhsiang.com/) had in 2015. David thinks that Bob invented the name, Bob doesn't remember and Sol thinks the waiter might have come up with it (although we can almost certainly rule that option out). It certainly is better than the previous name "IAMF". We now use "Mimi" purely as a name of the package, not as an acronym.
@@ -11,21 +17,44 @@ covariance between estimated coefficient parameters.  For example, an estimated
 polynomial can be represented as a multivariate Normal distribution,
 with a variance-covariance matrix.  To use this, define the parameter
 in the component with a vector type, like here:
-```
-@defcomp example begin
-    cubiccoeffs::Vector{Float64} = Parameter()
+
+```jldoctest; output = false
+@defcomp MyComp begin
+    cubiccoeff::Vector{Float64} = Parameter()
 end
+
+ # output
 ```
 
 Then in the model construction, set the parameter with a multivariate
-distribution (here the parameters are loaded from a CSV file):
-```
-cubicparams = readdlm("../data/cubicparams.csv", ',')
-set_param!(m, :example, :cubiccoeff, MvNormal(squeeze(cubicparams[1,:], 1), cubicparams[2:4,:]))
+distribution:
+
+```jldoctest; output = false; setup = @defcomp MyComp begin cubiccoeff::Vector{Float64} = Parameter() end
+# First line: linear, quadratic, cubic
+# Lines 2-4: covariance matrix
+cubicparams = [
+    [-3.233303      1.911123    -0.1018884];
+    [ 1.9678593    -0.57211657   0.04413228];
+    [-0.57211657    0.17500949  -0.01388863];
+    [ 0.04413228   -0.01388863   0.00111965]
+]
+
+m = Model()
+set_dimension!(m, :time, collect(2015:5:2110))
+add_comp!(m, MyComp)
+
+set_param!(m, :MyComp, :cubiccoeff, MvNormal(cubicparams[1,:], cubicparams[2:4,:]))
+
+# output
 ```
 
-Here, `../data/cubicparams.csv` is a parameter definition file that looks something like this:
+Note that we could also load the data fom a file with:
+
+```julia
+cubicparams = readdlm("../data/cubicparams.csv", ',')
 ```
+where `../data/cubicparams.csv` would be a parameter definition file that looks something like this:
+```julia 
 # Example estimated polynomial parameter
 # First line: linear, quadratic, cubic
 # Lines 2-4: covariance matrix
@@ -38,13 +67,29 @@ Here, `../data/cubicparams.csv` is a parameter definition file that looks someth
 ## How do I use component references?
 
 Component references allow you to write cleaner model code when connecting components.  The `add_comp!` function returns a reference to the component that you just added:
-```
-mycomponent = add_comp!(model, MyComponent)
+
+```jldoctest; output = false; setup = @defcomp MyComp begin cubiccoeff::Vector{Float64} = Parameter() end
+m = Model()
+set_dimension!(m, :time, collect(2015:5:2110))
+
+mycomponent = add_comp!(m, MyComp)
+
+# output
+Mimi.ComponentReference(1-component Mimi.Model:
+  MyComp::Main.MyComp
+, :MyComp)
 ```
 
 If you want to get a reference to a component after the `add_comp!` call has been made, you can construct the reference as:
-```
-mycomponent = ComponentReference(model, :MyComponent)
+```jldoctest; setup = @defcomp MyComp begin cubiccoeff::Vector{Float64} = Parameter() end; m = Model(); set_dimension!(m, :time, collect(2015:5:2110)); add_comp!(m, MyComp)
+
+mycomponent = Mimi.ComponentReference(m, :MyComp)
+
+#output 
+Mimi.ComponentReference(1-component Mimi.Model:
+  MyComp::Main.MyComp
+, :MyComp)
+
 ```
 
 You can use this component reference in place of the `set_param!` and `connect_param!` calls.
@@ -56,3 +101,7 @@ The line `set_param!(model, :MyComponent, :myparameter, myvalue)` can be written
 ## References in place of `connect_param!`
 
 The line `connect_param!(model, :MyComponent, :myparameter, :YourComponent, :yourparameter)` can be written as `mycomponent[:myparameter] = yourcomponent[:yourparameter]`, where `mycomponent` and `yourcomponent` are component references.
+
+```@meta
+DocTestSetup = nothing
+```