From 541e35aaf4723b5729366c4af9ac82f868bfeecc Mon Sep 17 00:00:00 2001
From: Twan Koolen <koolen.twan@gmail.com>
Date: Mon, 15 Oct 2018 11:04:38 -0400
Subject: [PATCH 1/3] Basic Documenter setup.

---
 .gitignore                     |   2 +
 .travis.yml                    |  11 ++-
 REQUIRE                        |   1 +
 docs/Manifest.toml             | 130 +++++++++++++++++++++++++++++++++
 docs/Project.toml              |   3 +
 docs/make.jl                   |  31 ++++++++
 docs/src/api/debug.md          |   5 ++
 docs/src/api/functions.md      |  43 +++++++++++
 docs/src/api/lazyexpression.md |  19 +++++
 docs/src/api/model.md          |  40 ++++++++++
 docs/src/api/parameter.md      |   6 ++
 docs/src/index.md              |  43 +++++++++++
 src/Parametron.jl              |   3 +-
 src/debug.jl                   |  24 +++---
 src/functions.jl               |  20 +++++
 src/lazyexpression.jl          |  19 ++---
 src/mockmodel.jl               |  10 +--
 src/model.jl                   |  18 ++---
 src/parameter.jl               |  13 ++--
 test/debug.jl                  |   4 +-
 test/lazyexpression.jl         |  42 +++++------
 test/parameter.jl              |   4 +-
 22 files changed, 419 insertions(+), 72 deletions(-)
 create mode 100644 docs/Manifest.toml
 create mode 100644 docs/Project.toml
 create mode 100644 docs/make.jl
 create mode 100644 docs/src/api/debug.md
 create mode 100644 docs/src/api/functions.md
 create mode 100644 docs/src/api/lazyexpression.md
 create mode 100644 docs/src/api/model.md
 create mode 100644 docs/src/api/parameter.md
 create mode 100644 docs/src/index.md

diff --git a/.gitignore b/.gitignore
index 8c960ec..a3f1c57 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,5 @@
 *.jl.cov
 *.jl.*.cov
 *.jl.mem
+docs/build
+
diff --git a/.travis.yml b/.travis.yml
index e53ccda..8ad3a9a 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -12,8 +12,17 @@ matrix:
 branches:
   only:
     - master
-    - /^v[0-9]+\.[0-9]+\.[0-9]+$/ # version tags
+    - /^v\d+\.\d+(\.\d+)?(-\S*)?$/ # version tags
 notifications:
   email: false
 after_success:
   - julia -e 'import Pkg; Pkg.add("Coverage"); using Coverage; Codecov.submit(process_folder())'
+jobs:
+  include:
+    - stage: Documentation
+      julia: 1.0
+      os: linux
+      script:
+        - julia --project=docs -e 'using Pkg; Pkg.instantiate()'
+        - julia --project=docs --color=yes docs/make.jl
+      after_success: skip
diff --git a/REQUIRE b/REQUIRE
index 7db5295..18cd237 100644
--- a/REQUIRE
+++ b/REQUIRE
@@ -3,3 +3,4 @@ MathOptInterface 0.5 0.6
 MacroTools
 FunctionWrappers 0.1.0
 DocStringExtensions
+Documenter
diff --git a/docs/Manifest.toml b/docs/Manifest.toml
new file mode 100644
index 0000000..d1d8b5b
--- /dev/null
+++ b/docs/Manifest.toml
@@ -0,0 +1,130 @@
+[[Base64]]
+uuid = "2a0f44e3-6c83-55bd-87e4-b1978d98bd5f"
+
+[[Compat]]
+deps = ["Base64", "Dates", "DelimitedFiles", "Distributed", "InteractiveUtils", "LibGit2", "Libdl", "LinearAlgebra", "Markdown", "Mmap", "Pkg", "Printf", "REPL", "Random", "Serialization", "SharedArrays", "Sockets", "SparseArrays", "Statistics", "Test", "UUIDs", "Unicode"]
+git-tree-sha1 = "2d9e14d19bad3f9ad5cc5e4cffabc3cfa59de825"
+uuid = "34da2185-b29b-5c13-b0c7-acf172513d20"
+version = "1.3.0"
+
+[[Dates]]
+deps = ["Printf"]
+uuid = "ade2ca70-3891-5945-98fb-dc099432e06a"
+
+[[DelimitedFiles]]
+deps = ["Mmap"]
+uuid = "8bb1440f-4735-579b-a4ab-409b98df4dab"
+
+[[Distributed]]
+deps = ["LinearAlgebra", "Random", "Serialization", "Sockets"]
+uuid = "8ba89e20-285c-5b6f-9357-94700520ee1b"
+
+[[DocStringExtensions]]
+deps = ["LibGit2", "Markdown", "Pkg", "Test"]
+git-tree-sha1 = "a016e0bfe98a748c4488e2248c2ef4c67d6fdd35"
+uuid = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
+version = "0.5.0"
+
+[[Documenter]]
+deps = ["Base64", "DocStringExtensions", "InteractiveUtils", "LibGit2", "Logging", "Markdown", "Pkg", "REPL", "Random", "Test", "Unicode"]
+git-tree-sha1 = "d3d031cf580435034c8d3b7219a9799cdc9b6939"
+repo-rev = "a9c03611eea5f8721d1ce3b388be90db569e8fc5"
+repo-url = "https://github.com/JuliaDocs/Documenter.jl.git"
+uuid = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+version = "0.19.6+"
+
+[[FunctionWrappers]]
+deps = ["Compat", "Pkg"]
+git-tree-sha1 = "49bf793ebd37db5adaa7ac1eae96c2c97ec86db5"
+uuid = "069b7b12-0de2-55c6-9aab-29f3d0a68a2e"
+version = "1.0.0"
+
+[[InteractiveUtils]]
+deps = ["LinearAlgebra", "Markdown"]
+uuid = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
+
+[[LibGit2]]
+uuid = "76f85450-5226-5b5a-8eaa-529ad045b433"
+
+[[Libdl]]
+uuid = "8f399da3-3557-5675-b5ff-fb832c97cbdb"
+
+[[LinearAlgebra]]
+deps = ["Libdl"]
+uuid = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+
+[[Logging]]
+uuid = "56ddb016-857b-54e1-b83d-db4d58db5568"
+
+[[MacroTools]]
+deps = ["Compat"]
+git-tree-sha1 = "c443e1c8d58a4e9f61b708ad0a88286c7042145b"
+uuid = "1914dd2f-81c6-5fcd-8719-6d5c9610ff09"
+version = "0.4.4"
+
+[[Markdown]]
+deps = ["Base64"]
+uuid = "d6f4376e-aef5-505a-96c1-9c027394607a"
+
+[[MathOptInterface]]
+deps = ["Compat", "Pkg", "Unicode"]
+git-tree-sha1 = "6bb3530fb9ed16a2f9324d6de54ec5ab9e5822e0"
+uuid = "b8f27783-ece8-5eb3-8dc8-9495eed66fee"
+version = "0.5.1"
+
+[[Mmap]]
+uuid = "a63ad114-7e13-5084-954f-fe012c677804"
+
+[[Parametron]]
+deps = ["DocStringExtensions", "Documenter", "FunctionWrappers", "LinearAlgebra", "MacroTools", "MathOptInterface", "Pkg", "Random", "Test"]
+path = ".."
+uuid = "41fac6d6-0ffa-5bcc-b863-17dd4947be41"
+version = "0.3.0+"
+
+[[Pkg]]
+deps = ["Dates", "LibGit2", "Markdown", "Printf", "REPL", "Random", "SHA", "UUIDs"]
+uuid = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"
+
+[[Printf]]
+deps = ["Unicode"]
+uuid = "de0858da-6303-5e67-8744-51eddeeeb8d7"
+
+[[REPL]]
+deps = ["InteractiveUtils", "Markdown", "Sockets"]
+uuid = "3fa0cd96-eef1-5676-8a61-b3b8758bbffb"
+
+[[Random]]
+deps = ["Serialization"]
+uuid = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
+
+[[SHA]]
+uuid = "ea8e919c-243c-51af-8825-aaa63cd721ce"
+
+[[Serialization]]
+uuid = "9e88b42a-f829-5b0c-bbe9-9e923198166b"
+
+[[SharedArrays]]
+deps = ["Distributed", "Mmap", "Random", "Serialization"]
+uuid = "1a1011a3-84de-559e-8e89-a11a2f7dc383"
+
+[[Sockets]]
+uuid = "6462fe0b-24de-5631-8697-dd941f90decc"
+
+[[SparseArrays]]
+deps = ["LinearAlgebra", "Random"]
+uuid = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
+
+[[Statistics]]
+deps = ["LinearAlgebra", "SparseArrays"]
+uuid = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
+
+[[Test]]
+deps = ["Distributed", "InteractiveUtils", "Logging", "Random"]
+uuid = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+
+[[UUIDs]]
+deps = ["Random"]
+uuid = "cf7118a7-6976-5b1a-9a39-7adc72f591a4"
+
+[[Unicode]]
+uuid = "4ec0a83e-493e-50e2-b9ac-8f72acf5a8f5"
diff --git a/docs/Project.toml b/docs/Project.toml
new file mode 100644
index 0000000..813234b
--- /dev/null
+++ b/docs/Project.toml
@@ -0,0 +1,3 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Parametron = "41fac6d6-0ffa-5bcc-b863-17dd4947be41"
diff --git a/docs/make.jl b/docs/make.jl
new file mode 100644
index 0000000..fcfaaa9
--- /dev/null
+++ b/docs/make.jl
@@ -0,0 +1,31 @@
+# Workaround for JuliaLang/julia/pull/28625
+if Base.HOME_PROJECT[] !== nothing
+    Base.HOME_PROJECT[] = abspath(Base.HOME_PROJECT[])
+end
+
+using Documenter, Parametron
+
+makedocs(
+    modules = [Parametron, Parametron.Functions],
+    checkdocs = :exports,
+    format = :html,
+    root = @__DIR__,
+    sitename ="Parametron.jl",
+    authors = "Twan Koolen and contributors.",
+    pages = [
+        "Home" => "index.md",
+        "API" => [
+            "api/functions.md",
+            "api/parameter.md",
+            "api/lazyexpression.md",
+            "api/model.md",
+            "api/debug.md",
+        ]
+    ],
+    html_prettyurls = parse(Bool, get(ENV, "CI", "false")),
+)
+
+deploydocs(
+    repo = "github.com/tkoolen/Parametron.jl.git",
+    target = "build"
+)
diff --git a/docs/src/api/debug.md b/docs/src/api/debug.md
new file mode 100644
index 0000000..3a0088d
--- /dev/null
+++ b/docs/src/api/debug.md
@@ -0,0 +1,5 @@
+# Debugging Utilities
+
+```@docs
+findallocs
+```
diff --git a/docs/src/api/functions.md b/docs/src/api/functions.md
new file mode 100644
index 0000000..6ecce71
--- /dev/null
+++ b/docs/src/api/functions.md
@@ -0,0 +1,43 @@
+# Functions
+
+```@meta
+CurrentModule = Parametron.Functions
+```
+
+```@docs
+Functions
+```
+
+## Types
+
+```@docs
+LinearTerm
+QuadraticTerm
+AffineFunction
+QuadraticFunction
+```
+
+## Exported functions
+
+```@docs
+canonicalize
+canonicalize(::QuadraticTerm)
+canonicalize(::AffineFunction)
+canonicalize(::QuadraticFunction)
+canonicalize!
+```
+
+## In-place math functions (unexported)
+
+```@docs
+add!
+subtract!
+muladd!
+vecdot!
+vecadd!
+vecsubtract!
+matvecmul!
+bilinearmul!
+scale!
+vcat!
+```
diff --git a/docs/src/api/lazyexpression.md b/docs/src/api/lazyexpression.md
new file mode 100644
index 0000000..606028d
--- /dev/null
+++ b/docs/src/api/lazyexpression.md
@@ -0,0 +1,19 @@
+# LazyExpression
+
+## The `@expression` macro
+
+```@docs
+@expression
+```
+
+## The `LazyExpression` type
+
+```@docs
+Parametron.LazyExpression
+```
+
+## Wrapping `LazyExpression`s
+
+```@docs
+Parametron.wrap
+```
diff --git a/docs/src/api/model.md b/docs/src/api/model.md
new file mode 100644
index 0000000..d073e8b
--- /dev/null
+++ b/docs/src/api/model.md
@@ -0,0 +1,40 @@
+# Model
+
+## Creating a `Model`
+
+```@docs
+Model
+```
+
+## Creating Decision variables
+
+```@docs
+Variable
+```
+
+## Adding constraints and an objective function
+
+```@docs
+@constraint
+@objective
+setobjective!
+```
+
+## Solving
+
+```@docs
+solve!
+Parametron.setdirty!
+Parametron.initialize!
+Parametron.update!
+```
+
+## Accessing solver results
+
+```@docs
+value
+objectivevalue
+terminationstatus
+primalstatus
+dualstatus
+```
diff --git a/docs/src/api/parameter.md b/docs/src/api/parameter.md
new file mode 100644
index 0000000..cb45db2
--- /dev/null
+++ b/docs/src/api/parameter.md
@@ -0,0 +1,6 @@
+# Parameter
+
+```@autodocs
+Modules = [Parametron]
+Pages   = ["parameter.jl"]
+```
diff --git a/docs/src/index.md b/docs/src/index.md
new file mode 100644
index 0000000..834b5fb
--- /dev/null
+++ b/docs/src/index.md
@@ -0,0 +1,43 @@
+# Parametron.jl
+
+Parametron makes it easy to set up and efficiently (ideally, with zero allocation) solve instances of a parameterized family of optimization problems.
+
+Parametron interfaces with various solvers through MathOptInterface.jl, similar to JuMP. However, unlike JuMP, the focus of Parametron is on efficient and user-friendly problem modification.
+
+## Installation
+
+### Installing Julia
+
+Download links and more detailed instructions are available on the [Julia website](http://julialang.org/). The latest version of Parametron.jl requires Julia 0.7, but we recommend downloading 1.0 (the latest stable Julia release at the time of writing).
+
+!!! warning
+
+    Do **not** use `apt-get` or `brew` to install Julia, as the versions provided by these package managers tend to be out of date.
+
+### Installing Parametron
+
+To install the latest tagged release of Parametron, start Julia and enter `Pkg` mode by pressing `]`. Then simply run
+
+```julia
+add Parametron
+```
+
+To use the latest master version and work on the bleeding edge (generally, not recommended), instead run
+
+```julia
+add Parametron#master
+```
+
+A third option is to clone the repository (to the directory printed by `julia -e 'import Pkg; println(Pkg.devdir())'`):
+
+```julia
+dev Parametron
+```
+
+## Usage
+
+See the [README](https://github.com/tkoolen/Parametron.jl/blob/master/README.md) for usage examples.
+
+## API
+
+See the API section for detailed documentation of exported functions.
diff --git a/src/Parametron.jl b/src/Parametron.jl
index f7f6384..eca13ff 100644
--- a/src/Parametron.jl
+++ b/src/Parametron.jl
@@ -26,7 +26,8 @@ export
     objectivevalue,
     terminationstatus,
     primalstatus,
-    dualstatus
+    dualstatus,
+    findallocs
 
 # macros
 export
diff --git a/src/debug.jl b/src/debug.jl
index 0dce5ac..4e644cd 100644
--- a/src/debug.jl
+++ b/src/debug.jl
@@ -31,38 +31,38 @@ Utility function that can be used to track down allocations in [`LazyExpression`
 
 The following session shows the output of `findallocs` if the expression doesn't allocate:
 
-```julia
-julia> model = Parametron.MockModel(); x = [Variable(model) for i in 1 : 2];
+```jldoctest; setup = :(using Parametron; model = Parametron.mock_model())
+julia> x = [Variable(model) for i in 1 : 2];
 
 julia> param = Parameter{Int}(() -> 2, model)
 Parameter{Int64, …}(…)
 
 julia> expr = @expression param * x
-LazyExpression{FunctionWrapper{…}(LazyExpression{Parametron.Functions.#scale!, …}(…))}(…)
+LazyExpression{FunctionWrapper{…}(LazyExpression{typeof(Parametron.Functions.scale!), …}(…))}(…)
 
 julia> Parametron.findallocs(expr)
-LazyExpression{FunctionWrapper{…}(LazyExpression{Parametron.Functions.#scale!, …}(…))}(…): 0 bytes
-  [1]: Array{Parametron.Functions.LinearTerm{Int64},1}
+LazyExpression{FunctionWrapper{…}(LazyExpression{typeof(Parametron.Functions.scale!), …}(…))}(…): 0 bytes
+  [1]: Array{LinearTerm{Int64},1}
   [2]: Parameter{Int64, …}(…): 0 bytes
-  [3]: Array{Parametron.Functions.Variable,1}
+  [3]: Array{Variable,1}
 ```
 
 In this session, `param` allocates, and `findallocs` reports the allocation:
 
-```julia
-julia> model = Parametron.MockModel(); x = [Variable(model) for i in 1 : 2];
+```jldoctest; setup = :(using Parametron; using LinearAlgebra; model = Parametron.mock_model())
+julia> x = [Variable(model) for i in 1 : 2];
 
 julia> param = Parameter(() -> zeros(2), model)
 Parameter{Array{Float64,1}, …}(…)
 
 julia> expr = @expression param ⋅ x
-LazyExpression{FunctionWrapper{…}(LazyExpression{Parametron.Functions.#vecdot!, …}(…))}(…)
+LazyExpression{FunctionWrapper{…}(LazyExpression{typeof(Parametron.Functions.vecdot!), …}(…))}(…)
 
 julia> Parametron.findallocs(expr)
-LazyExpression{FunctionWrapper{…}(LazyExpression{Parametron.Functions.#vecdot!, …}(…))}(…): 0 bytes
-  [1]: Parametron.Functions.AffineFunction{Float64}
+LazyExpression{FunctionWrapper{…}(LazyExpression{typeof(Parametron.Functions.vecdot!), …}(…))}(…): 0 bytes
+  [1]: AffineFunction{Float64}
   [2]: Parameter{Array{Float64,1}, …}(…): 96 bytes
-  [3]: Array{Parametron.Functions.Variable,1}
+  [3]: Array{Variable,1}
 ```
 """
 findallocs(x) = findallocs(stdout, x)
diff --git a/src/functions.jl b/src/functions.jl
index c0d531c..3b85cdd 100644
--- a/src/functions.jl
+++ b/src/functions.jl
@@ -412,6 +412,8 @@ end
 $(SIGNATURES)
 
 Add `x` to `f`, modifying `f`.
+
+$(METHODLIST)
 """
 function add! end
 
@@ -432,6 +434,8 @@ add!(dest, x, y) = (copyto!(dest, x); add!(dest, y); dest)
 $(SIGNATURES)
 
 Subtract `x` from `f`, modifying `f`.
+
+$(METHODLIST)
 """
 function subtract! end
 
@@ -471,6 +475,8 @@ subtract!(dest, x, y) = (copyto!(dest, x); subtract!(dest, y); dest)
 $(SIGNATURES)
 
 Multiply `x` by `y` and add the result to `dest`.
+
+$(METHODLIST)
 """
 function muladd! end
 
@@ -613,6 +619,8 @@ Base.conj(x::ParametronFunctions) = x
 $(SIGNATURES)
 
 Take the dot product of vectors `x` and `y`, storing the result in `dest`.
+
+$(METHODLIST)
 """
 function vecdot! end
 
@@ -688,6 +696,8 @@ vecdot!(dest::QuadraticFunction, x::AbstractVector{<:AffineFunction}, y::Abstrac
 $(SIGNATURES)
 
 Add vector `x` to vector `y`, storing the result in `dest`.
+
+$(METHODLIST)
 """
 function vecadd! end
 
@@ -695,6 +705,8 @@ function vecadd! end
 $(SIGNATURES)
 
 Subtract vector `y` from vector `x`, storing the result in `dest`.
+
+$(METHODLIST)
 """
 function vecsubtract! end
 
@@ -717,6 +729,8 @@ end
 $(SIGNATURES)
 
 Compute the matrix-vector product `A * x`, storing the result in `y`.
+
+$(METHODLIST)
 """
 function matvecmul! end
 
@@ -780,6 +794,8 @@ end
 $(SIGNATURES)
 
 Compute the bilinear form `transpose(x) * A * y`, storing the result in `dest`.
+
+$(METHODLIST)
 """
 function bilinearmul! end
 
@@ -811,6 +827,8 @@ end
 $(SIGNATURES)
 
 Scale a vector by a number and store the result in `dest`.
+
+$(METHODLIST)
 """
 function scale! end
 
@@ -905,6 +923,8 @@ end
 $(SIGNATURES)
 
 Vertically concatenate a number of vectors, storing the result in `y`.
+
+$(METHODLIST)
 """
 function vcat! end
 
diff --git a/src/lazyexpression.jl b/src/lazyexpression.jl
index 3567e48..cad8f9c 100644
--- a/src/lazyexpression.jl
+++ b/src/lazyexpression.jl
@@ -12,11 +12,11 @@ A `LazyExpression` may be evaluated by simply calling it with no arguments.
 
 # Example
 
-```julia
+```jldoctest; setup = :(using Parametron)
 julia> a = ones(2); b = ones(2);
 
 julia> expr = Parametron.LazyExpression(+, a, b)
-LazyExpression{Base.#+, …}(…)
+LazyExpression{typeof(+), …}(…)
 
 julia> expr()
 2-element Array{Float64,1}:
@@ -100,17 +100,14 @@ are simply evaluated straight away.
 
 Creating an expression that represents `p * x1`, where `p` is a parameter that always evaluates to 2:
 
-```julia
-julia> model = Parametron.MockModel(); # a 'mock model' used only for demonstrations and tests
-
-julia> x1 = Variable(model)
-Parametron.Functions.Variable(1)
+```jldoctest; setup = :(using Parametron; model = Parametron.mock_model())
+julia> x1 = Variable(model);
 
 julia> p = Parameter{Int}(() -> 2, model)
 Parameter{Int64, …}(…)
 
 julia> expr = @expression p * x1
-LazyExpression{FunctionWrapper{…}(LazyExpression{Base.#*, …}(…))}(…)
+LazyExpression{FunctionWrapper{…}(LazyExpression{typeof(*), …}(…))}(…)
 
 julia> expr()
 2 * x1
@@ -119,8 +116,8 @@ julia> expr()
 Creating an expression that represents `p ⋅ x`, where `p` is a parameter that evaluates to [1, 2] and
 `x` is a vector of two variables:
 
-```julia
-julia> model = Parametron.MockModel();
+```jldoctest; setup = :(using Parametron; using LinearAlgebra; model = Parametron.mock_model())
+julia> model = Parametron.mock_model();
 
 julia> x = Variable.(1 : 2);
 
@@ -128,7 +125,7 @@ julia> p = Parameter(model, val=[1, 2])
 Parameter{Array{Int64,1}, …}(…)
 
 julia> expr = @expression p ⋅ x
-LazyExpression{FunctionWrapper{…}(LazyExpression{Parametron.Functions.#vecdot!, …}(…))}(…)
+LazyExpression{FunctionWrapper{…}(LazyExpression{typeof(Parametron.Functions.vecdot!), …}(…))}(…)
 
 julia> expr()
 1 * x1 + 2 * x2 + 0
diff --git a/src/mockmodel.jl b/src/mockmodel.jl
index bbd44bf..369cd69 100644
--- a/src/mockmodel.jl
+++ b/src/mockmodel.jl
@@ -1,8 +1,3 @@
-import Parametron
-
-"""
-A 'mock model' used only for demonstrations and tests.
-"""
 struct MockModel
     params::Vector{Parametron.Parameter}
     nextvarindex::Base.RefValue{Int}
@@ -11,3 +6,8 @@ MockModel() = MockModel(Parametron.Parameter[], Ref(1))
 Parametron.setdirty!(model::MockModel) = foreach(Parametron.setdirty!, model.params)
 Parametron.addparameter!(model::MockModel, param::Parametron.Parameter) = (push!(model.params, param); param)
 Variable(model::MockModel) = (ret = Variable(model.nextvarindex[]); model.nextvarindex[] += 1; ret);
+
+function mock_model()
+    optimizer = MOIU.MockOptimizer(Parametron.ParametronMOIModel{Float64}())
+    Parametron.Model(optimizer)
+end
diff --git a/src/model.jl b/src/model.jl
index 004d299..9220bc2 100644
--- a/src/model.jl
+++ b/src/model.jl
@@ -197,15 +197,14 @@ Add a constraint to the model using operators `==`, `<=`, `>=`, or `in`/`∈`.
 `in`/`∈` may only be used for single variables with a right hand side that is
 one of:
 
-* ℤ or Integers
-* {0, 1} or ZeroOne
+* `ℤ` or `Integers`
+* `{0, 1}` or `ZeroOne`
 
 # Examples
 
-Let `model` be a `Model` instance. The constraint `x >= zeros(2)` can
-be added as follows:
+The constraint `x >= zeros(2)` can be added to a model as follows:
 
-```julia
+```jldoctest constraint-macro; setup = :(using Parametron; model = Parametron.mock_model())
 julia> x = [Variable(model) for i = 1 : 2];
 
 julia> @constraint(model, x >= zeros(2))
@@ -214,8 +213,8 @@ julia> @constraint(model, x >= zeros(2))
 The constraint that variable `x[1]` should be an integer can be
 expressed using:
 
-```julia
-julia> @constraint(model, x ∈ ℤ)
+```jldoctest constraint-macro
+julia> @constraint(model, x[1] ∈ ℤ)
 ```
 """
 macro constraint(model, expr)
@@ -255,10 +254,11 @@ Set the objective function of the model.
 Let `model` be a `Model` instance. The objective 'minimize x ⋅ x' can
 be added as follows:
 
-```julia
+```jldoctest; setup = :(using Parametron; using LinearAlgebra; model = Parametron.mock_model())
 julia> x = [Variable(model) for i = 1 : 2];
 
-julia> @objective model Minimize x ⋅ x
+julia> @objective model Minimize x ⋅ x;
+```
 """
 macro objective(model, sense, expr)
     quote
diff --git a/src/parameter.jl b/src/parameter.jl
index 14ed5c5..fa7b10f 100644
--- a/src/parameter.jl
+++ b/src/parameter.jl
@@ -13,10 +13,7 @@ The update function will then be called when the parameter itself is called.
 
 # Examples
 
-```julia
-julia> model = Parametron.MockModel() # a 'mock model' used only for demonstrations and tests
-Parametron.MockModel(Parametron.Parameter[], Base.RefValue{Int64}(1))
-
+```jldoctest; setup = :(using Parametron; model = Parametron.mock_model())
 julia> value = Ref(1)
 Base.RefValue{Int64}(1)
 
@@ -42,21 +39,21 @@ struct Parameter{T, F, InPlace}
     val::Base.RefValue{T}
 
     # out-of-place
-    """
+    @doc """
     $(SIGNATURES)
 
     Create a new 'out-of-place' `Parameter` with an update function `f` that takes
     no arguments and returns a value of type `T`.
-    """
+    """ ->
     Parameter{T}(f::F, model) where {T, F} = addparameter!(model, new{T, F, false}(Ref(true), f, Base.RefValue{T}()))
 
     # in-place
-    """
+    @doc """
     $(SIGNATURES)
 
     Create a new 'in-place' `Parameter` with an update function `f` that takes
     `val` as its argument and updates it in place.
-    """
+    """ ->
     Parameter(f::F, val::T, model) where {T, F} = addparameter!(model, new{T, F, true}(Ref(true), f, Base.RefValue(val)))
 end
 
diff --git a/test/debug.jl b/test/debug.jl
index b24d1e3..4acd900 100644
--- a/test/debug.jl
+++ b/test/debug.jl
@@ -3,10 +3,10 @@ module DebugTest
 using Test
 using Parametron
 
-import Parametron: MockModel, setdirty!, findallocs
+import Parametron: mock_model, setdirty!, findallocs
 
 @testset "findallocs" begin
-    model = MockModel()
+    model = mock_model()
     x = Variable(model)
     p = Parameter{Int}(() -> 3, model)
     expr = @expression p * 4 + x
diff --git a/test/lazyexpression.jl b/test/lazyexpression.jl
index a3724ce..c1b91b2 100644
--- a/test/lazyexpression.jl
+++ b/test/lazyexpression.jl
@@ -7,10 +7,10 @@ using Parametron
 using StaticArrays
 
 import Random
-import Parametron: setdirty!, MockModel
+import Parametron: setdirty!, mock_model
 
 @testset "basics" begin
-    model = MockModel()
+    model = mock_model()
     a = 2
     b = Parameter{Int}(() -> 3, model)
     c = 4
@@ -23,7 +23,7 @@ end
 end
 
 @testset "parameter" begin
-    model = MockModel()
+    model = mock_model()
     a = 3
     b = 4.0
     cval = Ref(0)
@@ -37,7 +37,7 @@ end
 end
 
 @testset "nested" begin
-    model = MockModel()
+    model = mock_model()
     a = 3
     b = 4.0
     cval = Ref(5)
@@ -66,7 +66,7 @@ using .M
     updatemat! = let scalar = scalar # https://github.com/JuliaLang/julia/issues/15276
         mat -> (mat.angular .= scalar[]; mat.linear .= scalar[]; mat)
     end
-    model = MockModel()
+    model = mock_model()
     pmat = Parameter(updatemat!, mat, model)
     pmat_angular = @expression angular(pmat)
     result = pmat_angular()
@@ -82,7 +82,7 @@ using .M
 end
 
 @testset "matvecmul!" begin
-    m = MockModel()
+    m = mock_model()
     A = Parameter(rand!, zeros(3, 4), m)
     x = Variable.(1 : 4)
     expr = @expression A * x
@@ -108,7 +108,7 @@ end
 end
 
 @testset "StaticArrays" begin
-    m = MockModel()
+    m = mock_model()
     A = Parameter{SMatrix{3, 3, Int, 9}}(m) do
         @SMatrix ones(Int, 3, 3)
     end
@@ -136,7 +136,7 @@ end
 end
 
 @testset "mul! optimization" begin
-    m = MockModel()
+    m = mock_model()
     weight = Parameter(() -> 3, m)
     x = Variable.(1 : 3)
     expr = @expression weight * (x ⋅ x)
@@ -148,7 +148,7 @@ end
 end
 
 @testset "scale! optimization" begin
-    model = MockModel()
+    model = mock_model()
     x = [Variable(model) for _ in 1 : 3]
     dt = Parameter{Float64}(model) do
         2.0
@@ -187,7 +187,7 @@ end
 
 @testset "vcat optimization" begin
     Random.seed!(42)
-    m = MockModel()
+    m = mock_model()
     A = Parameter(rand!, zeros(3, 4), m)
     B = Parameter(rand!, zeros(3, 3), m)
     x = Variable.(1 : 4)
@@ -245,7 +245,7 @@ end
 end
 
 @testset "vect optimization" begin
-    m = MockModel()
+    m = mock_model()
     x = Variable.(1:2)
     p = Parameter(m) do
         SVector(1., 2.)
@@ -263,7 +263,7 @@ end
 end
 
 @testset "convert optimization" begin
-    m = MockModel()
+    m = mock_model()
     A = Parameter{SMatrix{3, 3, Int, 9}}(m) do
         @SMatrix ones(Int, 3, 3)
     end
@@ -277,7 +277,7 @@ end
 end
 
 @testset "vecdot optimization" begin
-    m = MockModel()
+    m = mock_model()
     x = Variable.(1:3)
     p = Parameter(m) do
         SVector(1., 2., 3.)
@@ -298,7 +298,7 @@ end
 end
 
 @testset "adjoint optimization" begin
-    m = MockModel()
+    m = mock_model()
     x = Variable.(1:2)
     p = Parameter(m) do
         @SMatrix [1. 2.; 3. 4.]
@@ -314,7 +314,7 @@ end
 end
 
 @testset "issue 26" begin
-    model = MockModel()
+    model = mock_model()
     n = 2
     x = Variable.(1 : n)
     vals = Dict(zip(x, rand(n)))
@@ -328,7 +328,7 @@ end
 end
 
 @testset "issue 32" begin
-    model = MockModel()
+    model = mock_model()
     v = [Variable(model) for _ in 1:2]
     v0 = zeros(2)
     Δt = 0.01
@@ -347,7 +347,7 @@ end
 end
 
 @testset "issue 23, fully qualified names" begin
-    model = MockModel()
+    model = mock_model()
     p = Parameter{Int}(() -> 2, model)
     expr = @expression Base.:+(2, p)
     @test expr() == 4
@@ -362,7 +362,7 @@ function allocations_in_local_scope(x)
 end
 
 @testset "getfield optimization" begin
-    model = MockModel()
+    model = mock_model()
     p = Parameter(model) do
         MyWrapper(rand())
     end
@@ -382,7 +382,7 @@ end
 end
 
 @testset "hcat" begin
-    model = MockModel()
+    model = mock_model()
     p = Parameter(model) do
         rand(3, 3)
     end
@@ -393,7 +393,7 @@ end
 end
 
 @testset "getindex" begin
-    model = MockModel()
+    model = mock_model()
     p = Parameter(model) do
         rand(3, 3)
     end
@@ -404,7 +404,7 @@ end
 end
 
 @testset "A' * x (https://github.com/tkoolen/Parametron.jl/pull/79#issuecomment-423732633)" begin
-    model = MockModel()
+    model = mock_model()
     n, m = 5, 15
     Adata = randn(n, m)
     A = Parameter(model, val=Adata)
diff --git a/test/parameter.jl b/test/parameter.jl
index a0ea2c6..35c0385 100644
--- a/test/parameter.jl
+++ b/test/parameter.jl
@@ -3,12 +3,12 @@ module ParameterTest
 using Test
 using Parametron
 
-import Parametron: setdirty!, MockModel
+import Parametron: setdirty!, mock_model
 
 @testset "Parameter" begin
     # out-of-place parameter
     val = Ref(true)
-    model = MockModel()
+    model = mock_model()
     p1 = Parameter{Bool}(() -> val[], model)
     @test p1()
 

From 0094d51db0c1236d15b3a7fb71137a9832ecd5ee Mon Sep 17 00:00:00 2001
From: Twan Koolen <koolen.twan@gmail.com>
Date: Mon, 15 Oct 2018 16:30:14 -0400
Subject: [PATCH 2/3] Deprecate MockModel()

---
 src/mockmodel.jl | 9 +--------
 1 file changed, 1 insertion(+), 8 deletions(-)

diff --git a/src/mockmodel.jl b/src/mockmodel.jl
index 369cd69..ac86e21 100644
--- a/src/mockmodel.jl
+++ b/src/mockmodel.jl
@@ -1,11 +1,4 @@
-struct MockModel
-    params::Vector{Parametron.Parameter}
-    nextvarindex::Base.RefValue{Int}
-end
-MockModel() = MockModel(Parametron.Parameter[], Ref(1))
-Parametron.setdirty!(model::MockModel) = foreach(Parametron.setdirty!, model.params)
-Parametron.addparameter!(model::MockModel, param::Parametron.Parameter) = (push!(model.params, param); param)
-Variable(model::MockModel) = (ret = Variable(model.nextvarindex[]); model.nextvarindex[] += 1; ret);
+Base.@deprecate MockModel() mock_model()
 
 function mock_model()
     optimizer = MOIU.MockOptimizer(Parametron.ParametronMOIModel{Float64}())

From 4b29a435ab05fcea63bc6cace95250c68b41e86d Mon Sep 17 00:00:00 2001
From: Twan Koolen <koolen.twan@gmail.com>
Date: Mon, 15 Oct 2018 16:43:37 -0400
Subject: [PATCH 3/3] Add doc badges.

---
 README.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/README.md b/README.md
index 7b6e299..2f21958 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,8 @@
 
 [![Build Status](https://travis-ci.org/tkoolen/Parametron.jl.svg?branch=master)](https://travis-ci.org/tkoolen/Parametron.jl)
 [![codecov.io](http://codecov.io/github/tkoolen/Parametron.jl/coverage.svg?branch=master)](http://codecov.io/github/tkoolen/Parametron.jl?branch=master)
+[![](https://img.shields.io/badge/docs-latest-blue.svg)](https://tkoolen.github.io/Parametron.jl/latest)
+[![](https://img.shields.io/badge/docs-stable-blue.svg)](https://tkoolen.github.io/Parametron.jl/stable)
 
 Parametron makes it easy to set up and efficiently (ideally, with *zero* allocation) solve instances of a **parameterized family** of optimization problems.