Merge pull request #69 from ArnoStrouwen/doc_improv

Doc improv

Author: ChrisRackauckas

.JuliaFormatter.toml

@@ -1 +1,2 @@
-style = "sciml"
+style = "sciml"
+format_markdown = true

LICENSE.md

@@ -1,22 +1,21 @@
 The PreallocationTools.jl package is licensed under the MIT "Expat" License:
 
 > Copyright (c) 2016-2020: ChrisRackauckas, Julia Computing.
->
+> 
 > Permission is hereby granted, free of charge, to any person obtaining a copy
 > of this software and associated documentation files (the "Software"), to deal
 > in the Software without restriction, including without limitation the rights
 > to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 > copies of the Software, and to permit persons to whom the Software is
 > furnished to do so, subject to the following conditions:
->
+> 
 > The above copyright notice and this permission notice shall be included in all
 > copies or substantial portions of the Software.
->
+> 
 > THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 > IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 > FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 > AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 > LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 > OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 > SOFTWARE.
->

README.md

@@ -7,7 +7,7 @@
 [![Build Status](https://github.com/SciML/PreallocationTools.jl/workflows/CI/badge.svg)](https://github.com/SciML/PreallocationTools.jl/actions?query=workflow%3ACI)
 [![Build status](https://badge.buildkite.com/8e62ff2622721bf7a82aa5effb466d311d53fe63dc89bf2f34.svg)](https://buildkite.com/julialang/preallocationtools-dot-jl)
 
-[![ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://img.shields.io/badge/ColPrac-Contributor's%20Guide-blueviolet)](https://github.com/SciML/ColPrac)
+[![ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://img.shields.io/badge/ColPrac-Contributor%27s%20Guide-blueviolet)](https://github.com/SciML/ColPrac)
 [![SciML Code Style](https://img.shields.io/static/v1?label=code%20style&message=SciML&color=9558b2&labelColor=389826)](https://github.com/SciML/SciMLStyle)
 
 PreallocationTools.jl is a set of tools for helping build non-allocating
@@ -30,7 +30,7 @@ needed.
 ### Using DiffCache
 
 ```julia
-DiffCache(u::AbstractArray, N::Int=ForwardDiff.pickchunksize(length(u)); levels::Int = 1)
+DiffCache(u::AbstractArray, N::Int = ForwardDiff.pickchunksize(length(u)); levels::Int = 1)
 DiffCache(u::AbstractArray, N::AbstractArray{<:Int})
 ```
 
@@ -73,7 +73,7 @@ randmat = rand(5, 3)
 sto = similar(randmat)
 stod = DiffCache(sto)
 
-function claytonsample!(sto, τ, α; randmat=randmat)
+function claytonsample!(sto, τ, α; randmat = randmat)
     sto = get_tmp(sto, τ)
     sto .= randmat
     τ == 0 && return sto
@@ -82,8 +82,8 @@ function claytonsample!(sto, τ, α; randmat=randmat)
     for i in 1:n
         v = sto[i, 2]
         u = sto[i, 1]
-        sto[i, 1] = (1 - u^(-τ) + u^(-τ)*v^(-(τ/(1 + τ))))^(-1/τ)*α
-        sto[i, 2] = (1 - u^(-τ) + u^(-τ)*v^(-(τ/(1 + τ))))^(-1/τ)
+        sto[i, 1] = (1 - u^(-τ) + u^(-τ) * v^(-(τ / (1 + τ))))^(-1 / τ) * α
+        sto[i, 2] = (1 - u^(-τ) + u^(-τ) * v^(-(τ / (1 + τ))))^(-1 / τ)
     end
     return sto
 end
@@ -108,7 +108,7 @@ function foo(du, u, (A, tmp), t)
     @. du = u + tmp
     nothing
 end
-prob = ODEProblem(foo, ones(5, 5), (0., 1.0), (ones(5,5), zeros(5,5)))
+prob = ODEProblem(foo, ones(5, 5), (0.0, 1.0), (ones(5, 5), zeros(5, 5)))
 solve(prob, TRBDF2())
 ```
 
@@ -125,8 +125,11 @@ function foo(du, u, (A, tmp), t)
     nothing
 end
 chunk_size = 5
-prob = ODEProblem(foo, ones(5, 5), (0., 1.0), (ones(5,5), DiffCache(zeros(5,5), chunk_size)))
-solve(prob, TRBDF2(chunk_size=chunk_size))
+prob = ODEProblem(foo,
+    ones(5, 5),
+    (0.0, 1.0),
+    (ones(5, 5), DiffCache(zeros(5, 5), chunk_size)))
+solve(prob, TRBDF2(chunk_size = chunk_size))
 ```
 
 or just using the default chunking:
@@ -140,9 +143,10 @@ function foo(du, u, (A, tmp), t)
     nothing
 end
 chunk_size = 5
-prob = ODEProblem(foo, ones(5, 5), (0., 1.0), (ones(5,5), DiffCache(zeros(5,5))))
+prob = ODEProblem(foo, ones(5, 5), (0.0, 1.0), (ones(5, 5), DiffCache(zeros(5, 5))))
 solve(prob, TRBDF2())
 ```
+
 ### DiffCache Example 3: Nested AD calls in an optimization problem involving a Hessian matrix
 
 ```julia
@@ -157,8 +161,8 @@ function foo(du, u, p, t)
 end
 
 coeffs = -collect(0.1:0.1:0.4)
-cache = DiffCache(zeros(2,2), levels = 3)
-prob = ODEProblem(foo, ones(2, 2), (0., 1.0), (coeffs, cache))
+cache = DiffCache(zeros(2, 2), levels = 3)
+prob = ODEProblem(foo, ones(2, 2), (0.0, 1.0), (coeffs, cache))
 realsol = solve(prob, TRBDF2(), saveat = 0.0:0.1:10.0, reltol = 1e-8)
 
 function objfun(x, prob, realsol, cache)
@@ -169,15 +173,16 @@ function objfun(x, prob, realsol, cache)
     if any((s.retcode != :Success for s in sol))
         ofv = 1e12
     else
-        ofv = sum((sol.-realsol).^2)
+        ofv = sum((sol .- realsol) .^ 2)
     end
     return ofv
 end
-fn(x,p) = objfun(x, p[1], p[2], p[3])
+fn(x, p) = objfun(x, p[1], p[2], p[3])
 optfun = OptimizationFunction(fn, Optimization.AutoForwardDiff())
 optprob = OptimizationProblem(optfun, zeros(length(coeffs)), (prob, realsol, cache))
 solve(optprob, Newton())
 ```
+
 Solves an optimization problem for the coefficients, `coeffs`, appearing in a differential equation.
 The optimization is done with [Optim.jl](https://github.com/JuliaNLSolvers/Optim.jl)'s `Newton()`
 algorithm. Since this involves automatic differentiation in the ODE solver and the calculation
@@ -206,7 +211,7 @@ construct.
 ## LazyBufferCache
 
 ```julia
-LazyBufferCache(f::F=identity)
+LazyBufferCache(f::F = identity)
 ```
 
 A `LazyBufferCache` is a `Dict`-like type for the caches which automatically defines
@@ -230,14 +235,14 @@ function foo(du, u, (A, lbc), t)
     @. du = u + tmp
     nothing
 end
-prob = ODEProblem(foo, ones(5, 5), (0., 1.0), (ones(5,5), LazyBufferCache()))
+prob = ODEProblem(foo, ones(5, 5), (0.0, 1.0), (ones(5, 5), LazyBufferCache()))
 solve(prob, TRBDF2())
 ```
 
 ## GeneralLazyBufferCache
 
 ```julia
-GeneralLazyBufferCache(f=identity)
+GeneralLazyBufferCache(f = identity)
 ```
 
 A `GeneralLazyBufferCache` is a `Dict`-like type for the caches which automatically defines
@@ -255,7 +260,7 @@ a DifferentialEquations `ODEIntegrator` object. This object is the one created v
 `DifferentialEquations.init(ODEProblem(ode_fnc, y₀, (0.0, T), p), Tsit5(); saveat = t)`, and we
 want to optimize `p` in a way that changes its type to ForwardDiff. Thus what we can do is make a
 GeneralLazyBufferCache which holds these integrator objects, defined by `p`, and indexing it with
-`p` in order to retrieve the cache. The first time it's called it will build the integrator, and 
+`p` in order to retrieve the cache. The first time it's called it will build the integrator, and
 in subsequent calls it will reuse the cache.
 
 Defining the cache as a function of `p` to build an integrator thus looks like:
@@ -269,7 +274,8 @@ end)
 then `lbc[p]` will be smart and reuse the caches. A full example looks like the following:
 
 ```julia
-using Random, DifferentialEquations, LinearAlgebra, Optimization, OptimizationNLopt, OptimizationOptimJL, PreallocationTools
+using Random, DifferentialEquations, LinearAlgebra, Optimization, OptimizationNLopt,
+    OptimizationOptimJL, PreallocationTools
 
 lbc = GeneralLazyBufferCache(function (p)
     DifferentialEquations.init(ODEProblem(ode_fnc, y₀, (0.0, T), p), Tsit5(); saveat = t)
@@ -290,13 +296,17 @@ function loglik(θ, data, integrator)
     reinit!(integrator, u0)
     solve!(integrator)
     ε = yᵒ .- integrator.sol.u
-    ℓ = -0.5n * log(2π * σ^2) - 0.5 / σ^2 * sum(ε.^2)
+    ℓ = -0.5n * log(2π * σ^2) - 0.5 / σ^2 * sum(ε .^ 2)
 end
 θ₀ = [-1.0, 0.5, 19.73]
 negloglik = (θ, p) -> -loglik(θ, p, lbc[θ[1]])
 fnc = OptimizationFunction(negloglik, Optimization.AutoForwardDiff())
 ε = zeros(n)
-prob = OptimizationProblem(fnc, θ₀, (yᵒ, n, ε), lb=[-10.0, 1e-6, 0.5], ub=[10.0, 10.0, 25.0])
+prob = OptimizationProblem(fnc,
+    θ₀,
+    (yᵒ, n, ε),
+    lb = [-10.0, 1e-6, 0.5],
+    ub = [10.0, 10.0, 25.0])
 solve(prob, LBFGS())
 ```
 

docs/make.jl

@@ -6,12 +6,20 @@ cp("./docs/Project.toml", "./docs/src/assets/Project.toml", force = true)
 include("pages.jl")
 
 makedocs(sitename = "PreallocationTools.jl",
-         authors = "Chris Rackauckas",
-         modules = [PreallocationTools],
-         clean = true,
-         doctest = false,
-         format = Documenter.HTML(assets = ["assets/favicon.ico"],
-                                  canonical = "https://docs.sciml.ai/PreallocationTools/stable/"),
-         pages = pages)
+    authors = "Chris Rackauckas",
+    modules = [PreallocationTools],
+    clean = true, doctest = false, linkcheck = true,
+    strict = [
+        :doctest,
+        :linkcheck,
+        :parse_error,
+        :example_block,
+        :cross_references,
+        # Other available options are
+        # :autodocs_block, :cross_references, :docs_block, :eval_block, :example_block, :footnote, :meta_block, :missing_docs, :setup_block
+    ],
+    format = Documenter.HTML(assets = ["assets/favicon.ico"],
+        canonical = "https://docs.sciml.ai/PreallocationTools/stable/"),
+    pages = pages)
 
 deploydocs(repo = "github.com/SciML/PreallocationTools.jl.git"; push_preview = true)