Merge pull request #66 from ArnoStrouwen/doc_improv

various doc and style improvements

Author: ChrisRackauckas

.JuliaFormatter.toml

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

LICENSE.md

@@ -19,4 +19,3 @@ The MultiScaleModels.jl package is licensed under the MIT "Expat" License:
 > 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

@@ -6,7 +6,7 @@
 [![codecov](https://codecov.io/gh/SciML/MultiScaleArrays.jl/branch/master/graph/badge.svg?token=FwXaKBNW67)](https://codecov.io/gh/SciML/MultiScaleArrays.jl)
 [![Build Status](https://github.com/SciML/MultiScaleArrays.jl/workflows/CI/badge.svg)](https://github.com/SciML/MultiScaleArrays.jl/actions?query=workflow%3ACI)
 
-[![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)
 
 MultiScaleArrays.jl allows you to easily build multiple scale models which are
@@ -38,17 +38,17 @@ using MultiScaleArrays
 struct Cell{B} <: AbstractMultiScaleArrayLeaf{B}
     values::Vector{B}
 end
-struct Population{T<:AbstractMultiScaleArray,B<:Number} <: AbstractMultiScaleArray{B}
+struct Population{T <: AbstractMultiScaleArray, B <: Number} <: AbstractMultiScaleArray{B}
     nodes::Vector{T}
     values::Vector{B}
     end_idxs::Vector{Int}
 end
-struct Tissue{T<:AbstractMultiScaleArray,B<:Number} <: AbstractMultiScaleArray{B}
+struct Tissue{T <: AbstractMultiScaleArray, B <: Number} <: AbstractMultiScaleArray{B}
     nodes::Vector{T}
     values::Vector{B}
     end_idxs::Vector{Int}
 end
-struct Embryo{T<:AbstractMultiScaleArray,B<:Number} <: AbstractMultiScaleArrayHead{B}
+struct Embryo{T <: AbstractMultiScaleArray, B <: Number} <: AbstractMultiScaleArrayHead{B}
     nodes::Vector{T}
     values::Vector{B}
     end_idxs::Vector{Int}
@@ -59,22 +59,18 @@ This setup defines a type structure which is both a tree and an array. A picture
 version is the following:
 
 <img src="https://user-images.githubusercontent.com/1814174/27211626-79fe1b9a-520f-11e7-87f1-1cb33da91609.PNG">
-
 Let's build a version of this. Using the constructors we can directly construct leaf types:
-
 ```julia
 cell1 = Cell([1.0; 2.0; 3.0])
 cell2 = Cell([4.0; 5.0])
 ```
-
 and build types higher up in the hierarchy by using the `constuct` method. The method
 is `construct(T::AbstractMultiScaleArray, nodes, values)`, though if `values` is not given it's
 taken to be empty.
-
 ```julia
 cell3 = Cell([3.0; 2.0; 5.0])
 cell4 = Cell([4.0; 6.0])
-population  = construct(Population, deepcopy([cell1, cell3, cell4]))
+population = construct(Population, deepcopy([cell1, cell3, cell4]))
 population2 = construct(Population, deepcopy([cell1, cell3, cell4]))
 population3 = construct(Population, deepcopy([cell1, cell3, cell4]))
 tissue1 = construct(Tissue, deepcopy([population, population2, population3])) # Make a Tissue from Populations

docs/make.jl

@@ -8,7 +8,15 @@ include("pages.jl")
 makedocs(sitename = "MultiScaleArrays.jl",
          authors = "Chris Rackauckas",
          modules = [MultiScaleArrays],
-         clean = true, doctest = false,
+         clean = true, doctest = false, linkcheck = true,
+         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://docs.sciml.ai/MultiScaleArrays/stable/"),

docs/src/index.md

@@ -31,17 +31,17 @@ using MultiScaleArrays
 struct Cell{B} <: AbstractMultiScaleArrayLeaf{B}
     values::Vector{B}
 end
-struct Population{T<:AbstractMultiScaleArray,B<:Number} <: AbstractMultiScaleArray{B}
+struct Population{T <: AbstractMultiScaleArray, B <: Number} <: AbstractMultiScaleArray{B}
     nodes::Vector{T}
     values::Vector{B}
     end_idxs::Vector{Int}
 end
-struct Tissue{T<:AbstractMultiScaleArray,B<:Number} <: AbstractMultiScaleArray{B}
+struct Tissue{T <: AbstractMultiScaleArray, B <: Number} <: AbstractMultiScaleArray{B}
     nodes::Vector{T}
     values::Vector{B}
     end_idxs::Vector{Int}
 end
-struct Embryo{T<:AbstractMultiScaleArray,B<:Number} <: AbstractMultiScaleArrayHead{B}
+struct Embryo{T <: AbstractMultiScaleArray, B <: Number} <: AbstractMultiScaleArrayHead{B}
     nodes::Vector{T}
     values::Vector{B}
     end_idxs::Vector{Int}
@@ -53,21 +53,21 @@ version is the following:
 
 ![](https://user-images.githubusercontent.com/1814174/27211626-79fe1b9a-520f-11e7-87f1-1cb33da91609.PNG)
 
-Let's build a version of this. Using the constructors we can directly construct leaf types:
+Let's build a version of this. Using the constructors, we can directly construct leaf types:
 
 ```julia
 cell1 = Cell([1.0; 2.0; 3.0])
 cell2 = Cell([4.0; 5.0])
 ```
 
 and build types higher up in the hierarchy by using the `constuct` method. The method
-is `construct(T::AbstractMultiScaleArray, nodes, values)`, though if `values` is not given it's
+is `construct(T::AbstractMultiScaleArray, nodes, values)`, though, if `values` is not given it's
 taken to be empty.
 
 ```julia
 cell3 = Cell([3.0; 2.0; 5.0])
 cell4 = Cell([4.0; 6.0])
-population  = construct(Population, deepcopy([cell1, cell3, cell4]))
+population = construct(Population, deepcopy([cell1, cell3, cell4]))
 population2 = construct(Population, deepcopy([cell1, cell3, cell4]))
 population3 = construct(Population, deepcopy([cell1, cell3, cell4]))
 tissue1 = construct(Tissue, deepcopy([population, population2, population3])) # Make a Tissue from Populations
@@ -95,66 +95,87 @@ techniques for each new model.
 
 ## Contributing
 
-- Please refer to the
-  [SciML ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://github.com/SciML/ColPrac/blob/master/README.md)
-  for guidance on PRs, issues, and other matters relating to contributing to ModelingToolkit.
-- There are a few community forums:
-    - the #diffeq-bridged channel in the [Julia Slack](https://julialang.org/slack/)
-    - [JuliaDiffEq](https://gitter.im/JuliaDiffEq/Lobby) on Gitter
-    - on the [Julia Discourse forums](https://discourse.julialang.org)
-    - see also [SciML Community page](https://sciml.ai/community/)
+  - Please refer to the
+    [SciML ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://github.com/SciML/ColPrac/blob/master/README.md)
+    for guidance on PRs, issues, and other matters relating to contributing to SciML.
+
+  - See the [SciML Style Guide](https://github.com/SciML/SciMLStyle) for common coding practices and other style decisions.
+  - There are a few community forums:
+    
+      + The #diffeq-bridged and #sciml-bridged channels in the
+        [Julia Slack](https://julialang.org/slack/)
+      + The #diffeq-bridged and #sciml-bridged channels in the
+        [Julia Zulip](https://julialang.zulipchat.com/#narrow/stream/279055-sciml-bridged)
+      + On the [Julia Discourse forums](https://discourse.julialang.org)
+      + See also [SciML Community page](https://sciml.ai/community/)
 
 ## Reproducibility
+
 ```@raw html
 <details><summary>The documentation of this SciML package was built using these direct dependencies,</summary>
 ```
+
 ```@example
 using Pkg # hide
 Pkg.status() # hide
 ```
+
 ```@raw html
 </details>
 ```
+
 ```@raw html
 <details><summary>and using this machine and Julia version.</summary>
 ```
+
 ```@example
 using InteractiveUtils # hide
 versioninfo() # hide
 ```
+
 ```@raw html
 </details>
 ```
+
 ```@raw html
 <details><summary>A more complete overview of all dependencies and their versions is also provided.</summary>
 ```
+
 ```@example
 using Pkg # hide
-Pkg.status(;mode = PKGMODE_MANIFEST) # hide
+Pkg.status(; mode = PKGMODE_MANIFEST) # hide
 ```
+
 ```@raw html
 </details>
 ```
+
 ```@raw html
 You can also download the 
 <a href="
 ```
+
 ```@eval
 using TOML
-version = TOML.parse(read("../../Project.toml",String))["version"]
-name = TOML.parse(read("../../Project.toml",String))["name"]
-link = "https://github.com/SciML/"*name*".jl/tree/gh-pages/v"*version*"/assets/Manifest.toml"
+version = TOML.parse(read("../../Project.toml", String))["version"]
+name = TOML.parse(read("../../Project.toml", String))["name"]
+link = "https://github.com/SciML/" * name * ".jl/tree/gh-pages/v" * version *
+       "/assets/Manifest.toml"
 ```
+
 ```@raw html
 ">manifest</a> file and the
 <a href="
 ```
+
 ```@eval
 using TOML
-version = TOML.parse(read("../../Project.toml",String))["version"]
-name = TOML.parse(read("../../Project.toml",String))["name"]
-link = "https://github.com/SciML/"*name*".jl/tree/gh-pages/v"*version*"/assets/Project.toml"
+version = TOML.parse(read("../../Project.toml", String))["version"]
+name = TOML.parse(read("../../Project.toml", String))["name"]
+link = "https://github.com/SciML/" * name * ".jl/tree/gh-pages/v" * version *
+       "/assets/Project.toml"
 ```
+
 ```@raw html
 ">project</a> file.
-```
+```

docs/src/multiscalearray.md

@@ -62,4 +62,4 @@ applies normal random numbers to the three values. We could use this to add to t
 model the fact that `tissue.values[1:3]` are the tissue's position, and `f` would then be
 adding Brownian motion.
 
-Of course, you can keep going and kind of do whatever you want. The power is yours!
+Of course, you can keep going and kind of do whatever you want. The power is yours!

src/MultiScaleArrays.jl

@@ -18,28 +18,28 @@ highest level of the model or the head extends MultiScaleModelHead, and all
 intermediate types extend AbstractMultiScaleArray. The leaf has an array `values::Vector{B}`.
 Each type above then contains three fields:
 
-- `nodes::Vector{T}`
-- `values::Vector{B}`
-- `end_idxs::Vector{Int}`
+  - `nodes::Vector{T}`
+  - `values::Vector{B}`
+  - `end_idxs::Vector{Int}`
 
 Note that the ordering of the fields matters.
 `B` is the `BottomType`, which has to be the same as the eltype for the array
 in the leaf types. `T` is another `AbstractMultiScaleArray`. Thus at each level,
 an` AbstractMultiScaleArray` contains some information of its own (`values`), the
-next level down in the heirarchy (`nodes`), and caching for indices (`end_idxs`).
+next level down in the hierarchy (`nodes`), and caching for indices (`end_idxs`).
 You can add and use extra fields as you please, and even make the types immutable.
 
 ## The MultiScaleModel API
 
 The resulting type acts as an array. A leaf type `l` acts exactly as an array
 with `l[i] == l.values[i]`. Higher nodes also act as a linear array. If `ln` is level
-`n` in the heirarchy, then `ln.nodes` is the vector of level `n-1` objects, and `ln.values`
+`n` in the hierarchy, then `ln.nodes` is the vector of level `n-1` objects, and `ln.values`
 are its "intrinsic values". There is an indexing scheme on `ln`, where:
 
-- `ln[i,j,k]` gets the `k`th `n-3` object in the `j`th `n-2` object in the `i`th level `n-1`
-  object. Of course, this recurses for the whole hierarchy.
-- `ln[i]` provides a linear index through all `.nodes` and `.values` values in every lower
-  level and `ln.values` itself.
+  - `ln[i,j,k]` gets the `k`th `n-3` object in the `j`th `n-2` object in the `i`th level `n-1`
+    object. Of course, this recurses for the whole hierarchy.
+  - `ln[i]` provides a linear index through all `.nodes` and `.values` values in every lower
+    level and `ln.values` itself.
 
 Thus `typeof(ln) <: AbstractVector{B}` where `B` is the eltype of its leaves and
 all `.values`'s.
@@ -66,7 +66,7 @@ operations:
 
 ```julia
 embryo[10] = 4.0 # changes protein concentration 10
-embryo[2,3,1] # Gives the 1st cell in the 3rd population of the second tissue
+embryo[2, 3, 1] # Gives the 1st cell in the 3rd population of the second tissue
 embryo[:] # generates a vector of all of the protein concentrations
 eachindex(embryo) # generates an iterator for the indices
 ```
@@ -77,18 +77,18 @@ Using the iterators, note that we can get each cell population by looping throug
 2 levels below the top, so
 
 ```julia
-for cell in level_iter(embryo,3)
-  # Do something with the cells!
+for cell in level_iter(embryo, 3)
+    # Do something with the cells!
 end
 ```
 
 or the multiple level iter, which is the one generally used in
 DifferentialEquations.jl functions:
 
 ```julia
-for (cell, dcell) in LevelIter(3,embryo, dembryo)
+for (cell, dcell) in LevelIter(3, embryo, dembryo)
     # If these are similar structures, `cell` and `dcell` are the similar parts
-    cell_ode(dcell,cell,p,t)
+    cell_ode(dcell, cell, p, t)
 end
 ```
 
@@ -112,7 +112,7 @@ remove_node!(embryo, 2, 1) # Removes population 1 from tissue 2 of the embryo
 ```
 
 Combined with event handling, this allows for dynamic structures to be derived from
-low level behaviors.
+low-level behaviors.
 
 ## Heterogeneous Nodes via Tuples
 
@@ -121,41 +121,47 @@ heterogeneous nodes. This could be useful for mixing types
 inside of the nodes. For example:
 
 ```julia
-struct PlantSettings{T} x::T end
-struct OrganParams{T} y::T end
+struct PlantSettings{T}
+    x::T
+end
+struct OrganParams{T}
+    y::T
+end
 
-struct Organ{B<:Number,P} <: AbstractMultiScaleArrayLeaf{B}
+struct Organ{B <: Number, P} <: AbstractMultiScaleArrayLeaf{B}
     values::Vector{B}
     name::Symbol
     params::P
 end
 
-struct Plant{B,S,N<:Tuple{Vararg{<:Organ{<:Number}}}} <: AbstractMultiScaleArray{B}
+struct Plant{B, S, N <: Tuple{Vararg{<:Organ{<:Number}}}} <: AbstractMultiScaleArray{B}
     nodes::N
     values::Vector{B}
     end_idxs::Vector{Int}
     settings::S
 end
 
-struct Community{B,N<:Tuple{Vararg{<:Plant{<:Number}}}} <: AbstractMultiScaleArray{B}
+struct Community{B, N <: Tuple{Vararg{<:Plant{<:Number}}}} <: AbstractMultiScaleArray{B}
     nodes::N
     values::Vector{B}
     end_idxs::Vector{Int}
 end
 
-mutable struct Scenario{B,N<:Tuple{Vararg{<:Community{<:Number}}}} <: AbstractMultiScaleArrayHead{B}
+mutable struct Scenario{B, N <: Tuple{Vararg{<:Community{<:Number}}}} <:
+               AbstractMultiScaleArrayHead{B}
     nodes::N
     values::Vector{B}
     end_idxs::Vector{Int}
 end
 
-organ1 = Organ([1.1,2.1,3.1], :Shoot, OrganParams(:grows_up))
-organ2 = Organ([4.1,5.1,6.1], :Root, OrganParams("grows down"))
-organ3 = Organ([1.2,2.2,3.2], :Shoot, OrganParams(true))
-organ4 = Organ([4.2,5.2,6.2], :Root, OrganParams(1//3))
+organ1 = Organ([1.1, 2.1, 3.1], :Shoot, OrganParams(:grows_up))
+organ2 = Organ([4.1, 5.1, 6.1], :Root, OrganParams("grows down"))
+organ3 = Organ([1.2, 2.2, 3.2], :Shoot, OrganParams(true))
+organ4 = Organ([4.2, 5.2, 6.2], :Root, OrganParams(1 // 3))
 plant1 = construct(Plant, (deepcopy(organ1), deepcopy(organ2)), Float64[], PlantSettings(1))
-plant2 = construct(Plant, (deepcopy(organ3), deepcopy(organ4)), Float64[], PlantSettings(1.0))
-community = construct(Community, (deepcopy(plant1), deepcopy(plant2), ))
+plant2 = construct(Plant, (deepcopy(organ3), deepcopy(organ4)), Float64[],
+                   PlantSettings(1.0))
+community = construct(Community, (deepcopy(plant1), deepcopy(plant2)))
 scenario = construct(Scenario, (deepcopy(community),))
 ```
 

src/math.jl

@@ -69,7 +69,9 @@ nnodes(A, Bs...) = common_number(nnodes(A), _nnodes(Bs))
 _nnodes(args::Tuple{Any}) = nnodes(args[1])
 _nnodes(args::Tuple{}) = 0
 
-"`A = find_amsa(As)` returns the first AMSA among the arguments."
+"""
+`A = find_amsa(As)` returns the first AMSA among the arguments.
+"""
 find_amsa(bc::Base.Broadcast.Broadcasted) = find_amsa(bc.args)
 find_amsa(args::Tuple) = !isempty(args) && find_amsa(find_amsa(args[1]), Base.tail(args))
 find_amsa(x) = x