Merge pull request #1572 from SciML/fb/builddocs

Run examples in docs

Author: YingboMa

docs/Project.toml

@@ -1,6 +1,17 @@
 [deps]
+BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
+DifferentialEquations = "0c46a032-eb83-5123-abaf-570d42b7fbaa"
+Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+GalacticOptim = "a75be94c-b780-496d-a8a9-0878b188d577"
+LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 ModelingToolkit = "961ee093-0014-501f-94e3-6117800e7a78"
+NonlinearSolve = "8913a72c-1f9b-4ce2-8d82-65094dcecaec"
+Optim = "429524aa-4258-5aef-a3af-852621145aeb"
+OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed"
+Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
+Symbolics = "0c5d862f-8b57-4792-8d23-62f2024744c7"
+Unitful = "1986cc42-f94f-5a68-af5c-568840ba703d"
 
 [compat]
 Documenter = "0.27"

docs/make.jl

@@ -5,6 +5,14 @@ makedocs(
     authors="Chris Rackauckas",
     modules=[ModelingToolkit],
     clean=true,doctest=false,
+    strict=[
+        :doctest, 
+        :linkcheck, 
+        :parse_error,
+        :example_block,
+        # Other available options are
+        # :autodocs_block, :cross_references, :docs_block, :eval_block, :example_block, :footnote, :meta_block, :missing_docs, :setup_block
+    ],
     format=Documenter.HTML(analytics = "UA-90474609-3",
                            assets=["assets/favicon.ico"],
                            canonical="https://mtk.sciml.ai/stable/"),

docs/src/basics/Composition.md

@@ -14,7 +14,7 @@ forcing later. Here, the library author defines a component named
 saying the forcing term of `decay1` is a constant while the forcing term
 of `decay2` is the value of the state variable `x`.
 
-```julia
+```@example composition
 using ModelingToolkit
 
 function decay(;name)
@@ -48,16 +48,11 @@ equations(connected)
 simplified_sys = structural_simplify(connected)
 
 equations(simplified_sys)
-
-#3-element Vector{Equation}:
-# Differential(t)(decay1₊f(t)) ~ 0
-# Differential(t)(decay1₊x(t)) ~ decay1₊f(t) - (decay1₊a*(decay1₊x(t)))
-# Differential(t)(decay2₊x(t)) ~ decay1₊x(t) - (decay2₊a*(decay2₊x(t)))
 ```
 
 Now we can solve the system:
 
-```julia
+```@example composition
 x0 = [
   decay1.x => 1.0
   decay1.f => 0.0
@@ -179,7 +174,7 @@ let's assume we have three separate systems which we want to compose to a single
 one. This is how one could explicitly forward all states and parameters to the
 higher level system:
 
-```julia
+```@example compose
 using ModelingToolkit, OrdinaryDiffEq, Plots
 
 ## Library code
@@ -195,7 +190,7 @@ N = S + I + R
 @named ieqn = ODESystem([D(I) ~ β*S*I/N-γ*I])
 @named reqn = ODESystem([D(R) ~ γ*I])
 
-@named sir = compose(ODESystem([
+sir = compose(ODESystem([
                     S ~ ieqn.S,
                     I ~ seqn.I,
                     R ~ ieqn.R,
@@ -209,24 +204,21 @@ N = S + I + R
                         ieqn.β => β
                         ieqn.γ => γ
                         reqn.γ => γ
-                    ]), seqn, ieqn, reqn)
+                    ], name=:sir), seqn, ieqn, reqn)
 ```
 
 Note that the states are forwarded by an equality relationship, while
 the parameters are forwarded through a relationship in their default
 values. The user of this model can then solve this model simply by
 specifying the values at the highest level:
 
-```julia
+```@example compose
 sireqn_simple = structural_simplify(sir)
 
 equations(sireqn_simple)
+```
 
-# 3-element Vector{Equation}:
-#Differential(t)(seqn₊S(t)) ~ -seqn₊β*ieqn₊I(t)*seqn₊S(t)*(((ieqn₊I(t)) + (reqn₊R(t)) + (seqn₊S(t)))^-1)
-#Differential(t)(ieqn₊I(t)) ~ ieqn₊β*ieqn₊I(t)*seqn₊S(t)*(((ieqn₊I(t)) + (reqn₊R(t)) + (seqn₊S(t)))^-1) - (ieqn₊γ*(ieqn₊I(t)))
-#Differential(t)(reqn₊R(t)) ~ reqn₊γ*ieqn₊I(t)
-
+```@example compose
 ## User Code
 
 u0 = [seqn.S => 990.0,
@@ -270,7 +262,7 @@ single_state_variable ~ expression_involving_any_variables
 
 ### Example: Friction
 The system below illustrates how this can be used to model Coulomb friction
-```julia
+```@example events
 using ModelingToolkit, OrdinaryDiffEq, Plots
 function UnitMassWithFriction(k; name)
   @variables t x(t)=0 v(t)=0
@@ -290,7 +282,7 @@ plot(sol)
 ### Example: Bouncing ball
 In the documentation for DifferentialEquations, we have an example where a bouncing ball is simulated using callbacks which has an `affect!` on the state. We can model the same system using ModelingToolkit like this
 
-```julia
+```@example events
 @variables t x(t)=1 v(t)=0
 D = Differential(t)
 
@@ -313,7 +305,7 @@ plot(sol)
 
 ### Test bouncing ball in 2D with walls
 Multiple events? No problem! This example models a bouncing ball in 2D that is enclosed by two walls at $y = \pm 1.5$.
-```julia
+```@example events
 @variables t x(t)=1 y(t)=0 vx(t)=0 vy(t)=2
 D = Differential(t)
 

docs/src/mtkitize_tutorials/modelingtoolkitize.md

@@ -4,8 +4,8 @@ For some `DEProblem` types, automatic tracing functionality is already included
 via the `modelingtoolkitize` function. Take, for example, the Robertson ODE
 defined as an `ODEProblem` for DifferentialEquations.jl:
 
-```julia
-using DifferentialEquations
+```@example mtkize
+using DifferentialEquations, ModelingToolkit
 function rober(du,u,p,t)
   y₁,y₂,y₃ = u
   k₁,k₂,k₃ = p
@@ -20,12 +20,12 @@ prob = ODEProblem(rober,[1.0,0.0,0.0],(0.0,1e5),(0.04,3e7,1e4))
 If we want to get a symbolic representation, we can simply call `modelingtoolkitize`
 on the `prob`, which will return an `ODESystem`:
 
-```julia
+```@example mtkize
 sys = modelingtoolkitize(prob)
 ```
 
 Using this, we can symbolically build the Jacobian and then rebuild the ODEProblem:
 
-```julia
+```@example mtkize
 prob_jac = ODEProblem(sys,[],(0.0,1e5),jac=true)
 ```

docs/src/mtkitize_tutorials/modelingtoolkitize_index_reduction.md

@@ -7,7 +7,7 @@ pendulum which accidentally generates an index-3 DAE, and show how to use the
 
 ## Copy-Pastable Example
 
-```julia
+```@example indexred
 using ModelingToolkit
 using LinearAlgebra
 using OrdinaryDiffEq
@@ -55,7 +55,7 @@ As a good DifferentialEquations.jl user, one would follow
 [the mass matrix DAE tutorial](https://diffeq.sciml.ai/stable/tutorials/advanced_ode_example/#Handling-Mass-Matrices)
 to arrive at code for simulating the model:
 
-```julia
+```@example indexred
 using OrdinaryDiffEq, LinearAlgebra
 function pendulum!(du, u, p, t)
     x, dx, y, dy, T = u
@@ -143,7 +143,7 @@ the numerical code into symbolic code, run `dae_index_lowering` lowering,
 then transform back to numerical code with `ODEProblem`, and solve with a
 numerical solver. Let's try that out:
 
-```julia
+```@example indexred
 traced_sys = modelingtoolkitize(pendulum_prob)
 pendulum_sys = structural_simplify(dae_index_lowering(traced_sys))
 prob = ODEProblem(pendulum_sys, Pair[], tspan)
@@ -153,8 +153,6 @@ using Plots
 plot(sol, vars=states(traced_sys))
 ```
 
-![](https://user-images.githubusercontent.com/1814174/110587364-9524b400-8141-11eb-91c7-4e56ce4fa20b.png)
-
 Note that plotting using `states(traced_sys)` is done so that any
 variables which are symbolically eliminated, or any variable reorderings
 done for enhanced parallelism/performance, still show up in the resulting
@@ -166,16 +164,14 @@ constructor, we can remove the algebraic equations from the states of the
 system and fully transform the index-3 DAE into an index-0 ODE which can
 be solved via an explicit Runge-Kutta method:
 
-```julia
+```@example indexred
 traced_sys = modelingtoolkitize(pendulum_prob)
 pendulum_sys = structural_simplify(dae_index_lowering(traced_sys))
 prob = ODAEProblem(pendulum_sys, Pair[], tspan)
 sol = solve(prob, Tsit5(),abstol=1e-8,reltol=1e-8)
 plot(sol, vars=states(traced_sys))
 ```
 
-![](https://user-images.githubusercontent.com/1814174/110587362-9524b400-8141-11eb-8b77-d940f108ae72.png)
-
 And there you go: this has transformed the model from being too hard to
 solve with implicit DAE solvers, to something that is easily solved with
 explicit Runge-Kutta methods for non-stiff equations.

docs/src/mtkitize_tutorials/sparse_jacobians.md

@@ -10,7 +10,7 @@ process.
 First let's start out with an implementation of the 2-dimensional Brusselator
 partial differential equation discretized using finite differences:
 
-```julia
+```@example sparsejac
 using DifferentialEquations, ModelingToolkit
 
 const N = 32
@@ -49,14 +49,14 @@ prob = ODEProblem(brusselator_2d_loop,u0,(0.,11.5),p)
 
 Now let's use `modelingtoolkitize` to generate the symbolic version:
 
-```julia
-sys = modelingtoolkitize(prob_ode_brusselator_2d)
+```@example sparsejac
+sys = modelingtoolkitize(prob)
 ```
 
 Now we regenerate the problem using `jac=true` for the analytical Jacobian
 and `sparse=true` to make it sparse:
 
-```julia
+```@example sparsejac
 sparseprob = ODEProblem(sys,Pair[],(0.,11.5),jac=true,sparse=true)
 ```