Documentation fixes (#1268)

* Remove api.md and quickstart.md out of pages

Only three markdown pages are made, and the
current directory structure can be simplified.

* Add import statement to quickstart.md

* Use dynamic example and repl blocks in api.md

* Add doctest setup for StaticArraysCore.jl

See commit e9dbf325d69f in StaticArraysCore.jl

* Fix docstring code formatting

- Add backticks around declared code names
- Fix spacing before method headers
- Use fenced code blocks

* Fix markdown lists

Add spacing before list items so that markdown treats them as one list

* Add type and method headers to docstrings

* Add doctests

docs/make.jl

@@ -3,7 +3,9 @@ using StaticArrays
 using StaticArraysCore
 
 # Setup for doctests in docstrings
-DocMeta.setdocmeta!(StaticArrays, :DocTestSetup, :(using LinearAlgebra, StaticArrays))
+doctest_setup = :(using LinearAlgebra, StaticArrays)
+DocMeta.setdocmeta!(StaticArrays,     :DocTestSetup, doctest_setup)
+DocMeta.setdocmeta!(StaticArraysCore, :DocTestSetup, doctest_setup)
 
 makedocs(;
     modules = [StaticArrays, StaticArraysCore],
@@ -13,8 +15,8 @@ makedocs(;
     ),
     pages = [
         "Home" => "index.md",
-        "API" => "pages/api.md",
-        "Quick Start" => "pages/quickstart.md",
+        "API" => "api.md",
+        "Quick Start" => "quickstart.md",
         ],
     sitename = "StaticArrays.jl",
 )

docs/src/pages/api.md → docs/src/api.md

@@ -247,12 +247,14 @@ could be represented as a `Vector{SVector{3,Float64}}`.
 Another common way of storing the same data is as a 3×`N` `Matrix{Float64}`.
 Rather conveniently, such types have *exactly* the same binary layout in memory,
 and therefore we can use `reinterpret` to convert between the two formats
-```julia
+```@example copy
+using StaticArrays # hide
 function svectors(x::Matrix{T}, ::Val{N}) where {T,N}
     size(x,1) == N || error("sizes mismatch")
     isbitstype(T) || error("use for bitstypes only")
     reinterpret(SVector{N,T}, vec(x))
 end
+nothing # hide
 ```
 Such a conversion does not copy the data, rather it refers to the *same* memory.
 Arguably, a `Vector` of `SVector`s is often preferable to a `Matrix` because it
@@ -263,31 +265,19 @@ However, the resulting object is a Base.ReinterpretArray, not an Array, which
 carries some runtime penalty on every single access. If you can afford the
 memory for a copy and can live with the non-shared mutation semantics, then it
 is better to pull a copy by e.g.
-```julia
+```@example copy
 function svectorscopy(x::Matrix{T}, ::Val{N}) where {T,N}
     size(x,1) == N || error("sizes mismatch")
     isbitstype(T) || error("use for bitstypes only")
     copy(reinterpret(SVector{N,T}, vec(x)))
 end
+nothing # hide
 ```
 For example:
-```
-julia> M=reshape(collect(1:6), (2,3))
-2×3 Array{Int64,2}:
- 1  3  5
- 2  4  6
-
-julia> svectors(M, Val{2}())
-3-element reinterpret(SArray{Tuple{2},Int64,1,2}, ::Array{Int64,1}):
- [1, 2]
- [3, 4]
- [5, 6]
-
-julia> svectorscopy(M, Val{2}())
-3-element Array{SArray{Tuple{2},Int64,1,2},1}:
- [1, 2]
- [3, 4]
- [5, 6]
+```@repl copy
+M = reshape(collect(1:6), (2,3))
+svectors(M, Val{2}())
+svectorscopy(M, Val{2}())
 ```
 
 ### Working with mutable and immutable arrays

docs/src/pages/quickstart.md → docs/src/quickstart.md

@@ -1,6 +1,7 @@
 # Quick Start
 
 ```julia
+import Pkg
 Pkg.add("StaticArrays")  # or Pkg.clone("https://github.com/JuliaArrays/StaticArrays.jl")
 using StaticArrays
 using LinearAlgebra

src/SArray.jl

@@ -28,26 +28,29 @@ shape_string(inds::CartesianIndex) = join(Tuple(inds), '×')
     Expr(:block, stmts...)
 end
 """
-   sacollect(SA, gen)
+    sacollect(SA, gen)
 
 Construct a statically-sized vector of type `SA`.from a generator
 `gen`. `SA` needs to have a size parameter since the length of `vec`
 is unknown to the compiler. `SA` can optionally specify the element
 type as well.
 
 Example:
-
-    sacollect(SVector{3, Int}, 2i+1 for i in 1:3)
-    sacollect(SMatrix{2, 3}, i+j for i in 1:2, j in 1:3)
-    sacollect(SArray{2, 3}, i+j for i in 1:2, j in 1:3)
+```julia
+sacollect(SVector{3, Int}, 2i+1 for i in 1:3)
+sacollect(SMatrix{2, 3}, i+j for i in 1:2, j in 1:3)
+sacollect(SArray{2, 3}, i+j for i in 1:2, j in 1:3)
+```
 
 This creates the same statically-sized vector as if the generator were
 collected in an array, but is more efficient since no array is
 allocated.
 
 Equivalent:
 
-    SVector{3, Int}([2i+1 for i in 1:3])
+```julia
+SVector{3, Int}([2i+1 for i in 1:3])
+```
 """
 sacollect
 
@@ -304,19 +307,19 @@ end
 A convenience macro to construct `SArray` with arbitrary dimension.
 It supports:
 1. (typed) array literals.
-!!! note
-    Every argument inside the square brackets is treated as a scalar during expansion.
-    Thus `@SArray[a; b]` always forms a `SVector{2}` and `@SArray [a b; c]` always throws
-    an error.
+   !!! note
+       Every argument inside the square brackets is treated as a scalar during expansion.
+       Thus `@SArray[a; b]` always forms a `SVector{2}` and `@SArray [a b; c]` always throws
+       an error.
 
 2. comprehensions
-!!! note
-    The range of a comprehension is evaluated at global scope by the macro, and must be
-    made of combinations of literal values, functions, or global variables.
+   !!! note
+       The range of a comprehension is evaluated at global scope by the macro, and must be
+       made of combinations of literal values, functions, or global variables.
 
 3. initialization functions
-!!! note
-    Only support `zeros()`, `ones()`, `fill()`, `rand()`, `randn()`, and `randexp()`
+   !!! note
+       Only support `zeros()`, `ones()`, `fill()`, `rand()`, `randn()`, and `randexp()`
 """
 macro SArray(ex)
     static_array_gen(SArray, ex, __module__)

src/arraymath.jl

@@ -182,7 +182,7 @@ end
 """
     arithmetic_closure(T)
 
-Return the type which values of type `T` will promote to under a combination of the arithmetic operations `+, -, *` and `/`.
+Return the type which values of type `T` will promote to under a combination of the arithmetic operations `+`, `-`, `*` and `/`.
 
 ```jldoctest
 julia> import StaticArrays.arithmetic_closure

src/convert.jl

@@ -60,21 +60,29 @@ The adaption rules for official `StaticArray`s could be summarized as:
 
 # `SA <: Union{SArray, MArray, SHermitianCompact, SizedArray}`: `size`/`eltype` adaptable
 
-- SA(x::Tuple)
- If `SA` is fully static-sized, then we first try to fill `SA` with `x`'s elements.
- If failed and `length(SA) == 1`, then we try to fill `SA` with `x` itself.
-
- If `SA` is not fully static-sized, then we always try to fill `SA` with `x`'s elements,
- and the constructor's `Size` is derived based on:
- 1. If `SA <: StaticVector`, then we use `length(x)` as the output `Length` 
- 2. If `SA <: StaticMatrix{M}`, then we use `(M, N)` (`N = length(x) ÷ M`) as the output `Size`
- 3. If `SA <: StaticMatrix{M,M} where M`, then we use `(N, N)` (`N = sqrt(length(x)`) as the output `Size`.
-- SA(x...)
- Similar to `Tuple`, but we never fill `SA` with `x` itself.
-- SA(x::StaticArray)
- We treat `x` as `Tuple` whenever possible. If failed, then try to inherit `x`'s `Size`.
-- SA(x::AbstractArray)
- `x` is used to provide eltype. Thus `SA` must be static sized.
+- `SA(x::Tuple)`
+
+  If `SA` is fully static-sized, then we first try to fill `SA` with `x`'s elements.
+  If failed and `length(SA) == 1`, then we try to fill `SA` with `x` itself.
+
+  If `SA` is not fully static-sized, then we always try to fill `SA` with `x`'s elements,
+  and the constructor's `Size` is derived based on:
+  1. If `SA <: StaticVector`, then we use `length(x)` as the output `Length`
+  2. If `SA <: StaticMatrix{M}`, then we use `(M, N)` (`N = length(x) ÷ M`) as the output `Size`
+  3. If `SA <: StaticMatrix{M,M} where M`, then we use `(N, N)` (`N = sqrt(length(x)`) as the output `Size`.
+
+- `SA(x...)`
+
+  Similar to `Tuple`, but we never fill `SA` with `x` itself.
+
+- `SA(x::StaticArray)`
+
+  We treat `x` as `Tuple` whenever possible. If failed, then try to inherit `x`'s `Size`.
+
+- `SA(x::AbstractArray)`
+
+  `x` is used to provide eltype. Thus `SA` must be static sized.
+
 """
 function construct_type(::Type{SA}, x) where {SA<:StaticArray}
     x isa BadArgs || return SA

src/initializers.jl

@@ -9,8 +9,8 @@ provided explicitly.
 # Examples:
 
 * `SA[1.0, 2.0]` creates a length-2 `SVector` of `Float64` elements.
-* `SA[1 2; 3 4]` creates a 2×2 SMatrix of `Int`s.
-* `SA[1 2]` creates a 1×2 SMatrix of `Int`s.
+* `SA[1 2; 3 4]` creates a 2×2 `SMatrix` of `Int`s.
+* `SA[1 2]` creates a 1×2 `SMatrix` of `Int`s.
 * `SA{Float32}[1, 2]` creates a length-2 `SVector` of `Float32` elements.
 
 A couple of helpful type aliases are also provided:

src/mapreduce.jl

@@ -6,8 +6,10 @@ A singleton type for representing "universal" initial value (identity element).
 The idea is that, given `op` for `mapfoldl`, virtually, we define an "extended"
 version of it by
 
-    op′(::_InitialValue, x) = x
-    op′(acc, x) = op(acc, x)
+```julia
+op′(::_InitialValue, x) = x
+op′(acc, x) = op(acc, x)
+```
 
 This is just a conceptually useful model to have in mind and we don't actually
 define `op′` here  (yet?).  But see `Base.BottomRF` for how it might work in

src/matrix_multiply.jl

@@ -19,7 +19,7 @@ import LinearAlgebra: BlasFloat, matprod, mul!
     mul_result_structure(a::Type, b::Type)
 
 Get a structure wrapper that should be applied to the result of multiplication of matrices
-of given types (a*b). 
+of given types (`a*b`).
 """
 function mul_result_structure(a, b)
     return identity

src/matrix_multiply_add.jl

@@ -87,7 +87,7 @@ end
 """
     gen_by_access(expr_gen, a::Type{<:AbstractArray}, b::Type{<:AbstractArray})
 
-Similar to gen_by_access with only one type argument. The difference is that tests for both
+Similar to `gen_by_access` with only one type argument. The difference is that tests for both
 arrays of type `a` and `b` are generated and `expr_gen` receives two access arguments,
 first for matrix `a` and the second for matrix `b`.
 """
@@ -175,7 +175,10 @@ function gen_by_access(expr_gen, a::Type{<:Diagonal{<:Any, <:StaticVector}}, b::
 end
 
 
-""" Size that stores whether a Matrix is a Transpose
+"""
+    TSize{S,T}
+
+Size that stores whether a Matrix is a Transpose.
 Useful when selecting multiplication methods, and avoiding allocations when dealing with
 the `Transpose` type by passing around the original matrix.
 Should pair with `parent`.
@@ -245,11 +248,19 @@ const StaticVecOrMatLikeForFiveArgMulDest{T} = Union{
     return _mul!(TSize(dest), mul_parent(dest), Size(A), Size(B), A, B, NoMulAdd{TMul, TDest}())
 end
 
-"Calculate the product of the dimensions being multiplied. Useful as a heuristic for unrolling."
+"""
+    multiplied_dimension(A, B)
+
+Calculate the product of the dimensions being multiplied. Useful as a heuristic for unrolling.
+"""
 @inline multiplied_dimension(A::Type{<:StaticVecOrMatLike}, B::Type{<:StaticVecOrMatLike}) =
     prod(size(A)) * size(B,2)
 
-"Validate the dimensions of a matrix multiplication, including matrix-vector products"
+"""
+    check_dims(sc, sa, sb)
+
+Validate the dimensions of a matrix multiplication, including matrix-vector products
+"""
 function check_dims(::Size{sc}, ::Size{sa}, ::Size{sb}) where {sa,sb,sc}
     if sb[1] != sa[2] || sc[1] != sa[1]
         return false
@@ -356,10 +367,12 @@ function uplo_access(sa, asym, k, j, uplo)
     end
 end
 
-""" Combine left and right sides of an assignment expression, short-cutting
-        lhs = α * rhs + β * lhs,
-    element-wise.
-If α = 1, the multiplication by α is removed. If β = 0, the second rhs term is removed.
+"""
+    _muladd_expr(lhs, rhs, coeffs)
+
+Combine left and right sides of an assignment expression, short-cutting
+`lhs = α * rhs + β * lhs`, element-wise.
+If `α = 1`, the multiplication by `α` is removed. If `β = 0`, the second `rhs` term is removed.
 """
 function _muladd_expr(lhs::Array{Expr}, rhs::Array{Expr}, ::Type{<:AlphaBeta})
     @assert length(lhs) == length(rhs)
@@ -378,7 +391,11 @@ end
     [:($(lhs[k]) = $(rhs[k])) for k = 1:length(lhs)]
 end
 
-"Obtain an expression for the linear index of var[k,j], taking transposes into account"
+"""
+    _lind(var, A, k, j)
+
+Obtain an expression for the linear index of `var[k,j]`, taking transposes into account.
+"""
 function _lind(var::Symbol, A::Type{TSize{sa,tA}}, k::Int, j::Int) where {sa,tA}
     ula = uplo_access(sa, var, k, j, tA)
     if ula.head == :call && ula.args[1] == :transpose

src/qr.jl

@@ -38,7 +38,7 @@ end
 
 Compute the QR factorization of `A`. The factors can be obtained by iteration:
 
-```julia
+```jldoctest qr
 julia> A = @SMatrix rand(3,4);
 
 julia> Q, R = qr(A);
@@ -49,7 +49,7 @@ true
 
 or by using `getfield`:
 
-```julia
+```jldoctest qr
 julia> F = qr(A);
 
 julia> F.Q * F.R ≈ A

src/traits.jl

@@ -89,7 +89,9 @@ the check is performed at runtime.
 @inline sizematch(::Size{S}, A::AbstractArray) where {S} = sizematch(S, size(A))
 
 """
-Return either the statically known Size() or runtime size()
+    _size(a)
+
+Return either the statically known `Size()` or runtime `size()`
 """
 @inline _size(a) = size(a)
 @inline _size(a::StaticArray) = Size(a)
@@ -100,7 +102,9 @@ Return either the statically known Size() or runtime size()
 @inline _first_static() = throw(ArgumentError("No StaticArray found in argument list"))
 
 """
-Returns the common Size of the inputs (or else throws a DimensionMismatch)
+    same_size(as...)
+
+Returns the common `Size` of the inputs (or else throws a `DimensionMismatch`)
 """
 @inline function same_size(as...)
     s = Size(_first_static(as...))