Merge pull request #1388 from abhro/patch-1

Documentation updates

Author: ChrisRackauckas

docs/src/manual/functions.md

@@ -151,7 +151,7 @@ Note that at this time array derivatives cannot be defined.
 
 ## Direct Registration API (Advanced, Experimental)
 
-!!! warn
+!!! warning
 
     This is a lower level API which is not as stable as the macro APIs.
 

docs/src/manual/parsing.md

@@ -7,10 +7,10 @@ to convert from Julia expressions to Symbolics.jl expressions for further
 manipulation. Towards this end is the `parse_expr_to_symbolic` which performs
 the parsing.
 
-!!! warn
+!!! warning
     Take the limitations mentioned in the `parse_expr_to_symbolic` docstrings
     seriously! Because Julia expressions contain no symbolic metadata, there
-    is limited information and thus the parsing requires heuristics to work. 
+    is limited information and thus the parsing requires heuristics to work.
 
 ```@docs
 parse_expr_to_symbolic

src/Symbolics.jl

@@ -68,7 +68,7 @@ include("complex.jl")
 
 Performs the substitution on `expr` according to rule(s) `s`.
 # Examples
-```julia
+```jldoctest
 julia> @variables t x y z(t)
 4-element Vector{Num}:
     t

src/arrays.jl

@@ -426,7 +426,7 @@ end
 """
     shape(s::Any)
 
-Returns `axes(s)` or Unknown().
+Returns `axes(s)` or `Unknown()`.
 """
 shape(s) = axes(s)
 

src/build_function.jl

@@ -34,18 +34,14 @@ function throw_missing_specialization(n)
 end
 
 """
-`build_function`
+    build_function(ex, args...;
+                   expression = Val{true},
+                   target = JuliaTarget(),
+                   parallel=nothing,
+                   kwargs...)
 
 Generates a numerically-usable function from a Symbolics `Num`.
 
-```julia
-build_function(ex, args...;
-               expression = Val{true},
-               target = JuliaTarget(),
-               parallel=nothing,
-               kwargs...)
-```
-
 Arguments:
 
 - `ex`: The `Num` to compile
@@ -220,16 +216,16 @@ end
 Build function target: `JuliaTarget`
 
 ```julia
-function _build_function(target::JuliaTarget, rhss, args...;
-                         conv = toexpr,
-                         expression = Val{true},
-                         checkbounds = false,
-                         linenumbers = false,
-                         headerfun = addheader, outputidxs=nothing,
-                         convert_oop = true, force_SA = false,
-                         skipzeros = outputidxs===nothing,
-                         fillzeros = skipzeros && !(typeof(rhss)<:SparseMatrixCSC),
-                         parallel=SerialForm(), kwargs...)
+_build_function(target::JuliaTarget, rhss, args...;
+                conv = toexpr,
+                expression = Val{true},
+                checkbounds = false,
+                linenumbers = false,
+                headerfun = addheader, outputidxs=nothing,
+                convert_oop = true, force_SA = false,
+                skipzeros = outputidxs===nothing,
+                fillzeros = skipzeros && !(typeof(rhss)<:SparseMatrixCSC),
+                parallel=SerialForm(), kwargs...)
 ```
 
 Generates a Julia function which can then be utilized for further evaluations.
@@ -676,11 +672,11 @@ end
 Build function target: `CTarget`
 
 ```julia
-function _build_function(target::CTarget, eqs::Array{<:Equation}, args...;
-                         conv = toexpr, expression = Val{true},
-                         fname = :diffeqf,
-                         lhsname=:du,rhsnames=[Symbol("RHS\$i") for i in 1:length(args)],
-                         libpath=tempname(),compiler=:gcc)
+_build_function(target::CTarget, eqs::Array{<:Equation}, args...;
+                conv = toexpr, expression = Val{true},
+                fname = :diffeqf,
+                lhsname=:du,rhsnames=[Symbol("RHS\$i") for i in 1:length(args)],
+                libpath=tempname(), compiler=:gcc)
 ```
 
 This builds an in-place C function. Only works on arrays of equations. If
@@ -689,7 +685,7 @@ and returns a lambda to that compiled function. These special keyword arguments
 control the compilation:
 
 - libpath: the path to store the binary. Defaults to a temporary path.
-- compiler: which C compiler to use. Defaults to :gcc, which is currently the
+- compiler: which C compiler to use. Defaults to `:gcc`, which is currently the
   only available option.
 """
 function _build_function(target::CTarget, eqs::Array{<:Equation}, args...;
@@ -736,15 +732,15 @@ end
 Build function target: `CTarget`
 
 ```julia
-function _build_function(target::CTarget, ex::AbstractArray, args...;
-                         columnmajor = true,
-                         conv        = toexpr,
-                         expression  = Val{true},
-                         fname       = :diffeqf,
-                         lhsname     = :du,
-                         rhsnames    = [Symbol("RHS\$i") for i in 1:length(args)],
-                         libpath     = tempname(),
-                         compiler    = :gcc)
+_build_function(target::CTarget, ex::AbstractArray, args...;
+                columnmajor = true,
+                conv        = toexpr,
+                expression  = Val{true},
+                fname       = :diffeqf,
+                lhsname     = :du,
+                rhsnames    = [Symbol("RHS\$i") for i in 1:length(args)],
+                libpath     = tempname(),
+                compiler    = :gcc)
 ```
 
 This builds an in-place C function. Only works on expressions. If
@@ -823,14 +819,14 @@ _build_function(target::CTarget, ex::Num, args...; kwargs...) = _build_function(
 Build function target: `StanTarget`
 
 ```julia
-function _build_function(target::StanTarget, eqs::Array{<:Equation}, vs, ps, iv;
-                         conv = toexpr, expression = Val{true},
-                         fname = :diffeqf, lhsname=:internal_var___du,
-                         rhsnames=[:internal_var___u,:internal_var___p,:internal_var___t])
+_build_function(target::StanTarget, eqs::Array{<:Equation}, vs, ps, iv;
+                conv = toexpr, expression = Val{true},
+                fname = :diffeqf, lhsname=:internal_var___du,
+                rhsnames=[:internal_var___u,:internal_var___p,:internal_var___t])
 ```
 
 This builds an in-place Stan function compatible with the Stan differential equation solvers.
-Unlike other build targets, this one requires (vs, ps, iv) as the function arguments.
+Unlike other build targets, this one requires `(vs, ps, iv)` as the function arguments.
 Only allowed on arrays of equations.
 """
 function _build_function(target::StanTarget, eqs::Array{<:Equation}, vs, ps, iv;
@@ -862,16 +858,16 @@ end
 Build function target: `StanTarget`
 
 ```julia
-function _build_function(target::StanTarget, ex::AbstractArray, vs, ps, iv;
-                         columnmajor = true,
-                         conv        = toexpr,
-                         expression  = Val{true},
-                         fname       = :diffeqf, lhsname=:internal_var___du,
-                         rhsnames    =  [:internal_var___u,:internal_var___p,:internal_var___t])
+_build_function(target::StanTarget, ex::AbstractArray, vs, ps, iv;
+                columnmajor = true,
+                conv        = toexpr,
+                expression  = Val{true},
+                fname       = :diffeqf, lhsname=:internal_var___du,
+                rhsnames    =  [:internal_var___u,:internal_var___p,:internal_var___t])
 ```
 
 This builds an in-place Stan function compatible with the Stan differential equation solvers.
-Unlike other build targets, this one requires (vs, ps, iv) as the function arguments.
+Unlike other build targets, this one requires `(vs, ps, iv)` as the function arguments.
 Only allowed on expressions, and arrays of expressions.
 """
 function _build_function(target::StanTarget, ex::AbstractArray, vs, ps, iv;
@@ -920,13 +916,13 @@ _build_function(target::StanTarget, ex::Num, vs, ps, iv; kwargs...) = _build_fun
 Build function target: `MATLABTarget`
 
 ```julia
-function _build_function(target::MATLABTarget, eqs::Array{<:Equation}, args...;
-                         conv = toexpr, expression = Val{true},
-                         lhsname=:internal_var___du,
-                         rhsnames=[:internal_var___u,:internal_var___p,:internal_var___t])
+_build_function(target::MATLABTarget, eqs::Array{<:Equation}, args...;
+                conv = toexpr, expression = Val{true},
+                lhsname=:internal_var___du,
+                rhsnames=[:internal_var___u,:internal_var___p,:internal_var___t])
 ```
 
-This builds an out of place anonymous function @(t,rhsnames[1]) to be used in MATLAB.
+This builds an out of place anonymous function `@(t,rhsnames[1])` to be used in MATLAB.
 Compatible with the MATLAB differential equation solvers. Only allowed on expressions,
 and arrays of expressions.
 """
@@ -953,13 +949,13 @@ end
 Build function target: `MATLABTarget`
 
 ```julia
-function _build_function(target::MATLABTarget, ex::AbstractArray, args...;
-                         columnmajor = true,
-                         conv        = toexpr,
-                         expression  = Val{true},
-                         fname       = :diffeqf,
-                         lhsname     = :internal_var___du,
-                         rhsnames    = [:internal_var___u,:internal_var___p,:internal_var___t])
+_build_function(target::MATLABTarget, ex::AbstractArray, args...;
+                columnmajor = true,
+                conv        = toexpr,
+                expression  = Val{true},
+                fname       = :diffeqf,
+                lhsname     = :internal_var___du,
+                rhsnames    = [:internal_var___u,:internal_var___p,:internal_var___t])
 ```
 
 This builds an out of place anonymous function @(t,rhsnames[1]) to be used in MATLAB.

src/diff.jl

@@ -170,13 +170,13 @@ and other derivative rules to expand any derivatives it encounters.
 ```jldoctest
 julia> @variables x y z k;
 
-julia> f=k*(abs(x-y)/y-z)^2
+julia> f = k*(abs(x-y)/y-z)^2
 k*((abs(x - y) / y - z)^2)
 
-julia> Dx=Differential(x) # Differentiate wrt x
+julia> Dx = Differential(x) # Differentiate wrt x
 (::Differential) (generic function with 2 methods)
 
-julia> dfx=expand_derivatives(Dx(f))
+julia> dfx = expand_derivatives(Dx(f))
 (k*((2abs(x - y)) / y - 2z)*IfElse.ifelse(signbit(x - y), -1, 1)) / y
 ```
 """

src/linear_algebra.jl

@@ -83,7 +83,7 @@ Currently only works if all equations are linear. `check` if the expr is linear
 w.r.t `vars`.
 
 # Examples
-```julia
+```jldoctest
 julia> @variables x y
 2-element Vector{Num}:
  x

src/operators.jl

@@ -32,7 +32,7 @@ end
 Get the time (in seconds) spent in a state in a finite state machine.
 
 When used to query the time spent in the enclosing state, the method without arguments is used, i.e.,
-```
+```julia
 @mtkmodel FSM begin
     ...
     @equations begin
@@ -56,7 +56,7 @@ timeInState
 Get the number of ticks spent in a state in a finite state machine.
 
 When used to query the number of ticks spent in the enclosing state, the method without arguments is used, i.e.,
-```
+```julia
 @mtkmodel FSM begin
     ...
     @equations begin

src/rewrite-helpers.jl

@@ -1,5 +1,6 @@
 """
-replacenode(expr::Symbolic, rules...)
+    replacenode(expr::Symbolic, rules...)
+
 Walk the expression and replacenode subexpressions according to `rules`. `rules`
 could be rules constructed with `@rule`, a function, or a pair where the
 left hand side is matched with equality (using `isequal`) and is replacenoded by the right hand side.
@@ -75,7 +76,8 @@ function _hasnode(r, y)
 end
 
 """
-filterchildren(c, x)
+    filterchildren(c, x)
+
 Returns all parts of `x` that fulfills the condition given in c. c can be a function or an expression.
 If it is a function, returns everything for which the function is `true`. If c is an expression, returns
 all expressions that matches it.

src/taylor.jl

@@ -10,7 +10,7 @@ Return the power series in `x` around `x0` to the powers `ns` with coefficients
 Examples
 ========
 
-```julia
+```jldoctest
 julia> @variables x y[0:3] z
 3-element Vector{Any}:
  x
@@ -47,7 +47,7 @@ Calculate the `n`-th order coefficient(s) in the Taylor series of `f` around `x
 
 Examples
 ========
-```julia
+```jldoctest
 julia> @variables x y
 2-element Vector{Num}:
  x
@@ -101,7 +101,7 @@ If `rationalize`, float coefficients are approximated as rational numbers (this
 
 Examples
 ========
-```julia
+```jldoctest
 julia> @variables x
 1-element Vector{Num}:
  x