Update docs (#951)

* Use sources path attribute for docs/Project.toml

* Fix markdown lists in docstrings

* Add doctests

* Change to markdown admoniton block

* Change preformat list to markdown list

* Add syntax highlight tags

* Center block level latex math

* Use markdown URL link syntax

* Use unicode characters in tex sections

They're supported by KaTeX for web rendering, and the characters take up less space when viewing the docstring on REPL or so

* Fix up spacing in docstrings

* Add type header to docstrings

* Fix doctests in weights.md

Author: abhro

docs/Project.toml

@@ -5,3 +5,6 @@ StatsAPI = "82ae8749-77ed-4fe6-ae5f-f523153014b0"
 
 [compat]
 Documenter = "1"
+
+[sources.StatsBase]
+path = ".."

docs/make.jl

@@ -5,6 +5,8 @@ if Base.HOME_PROJECT[] !== nothing
     Base.HOME_PROJECT[] = abspath(Base.HOME_PROJECT[])
 end
 
+DocMeta.setdocmeta!(StatsBase, :DocTestSetup, :(using StatsBase))
+
 makedocs(
     sitename = "StatsBase.jl",
     modules = [StatsBase, StatsAPI],

docs/src/index.md

@@ -19,7 +19,7 @@ Pkg.add("StatsBase")
 ```
 
 To load the package, use the command:
-```
+```julia
 using StatsBase
 ```
 

docs/src/weights.md

@@ -1,3 +1,8 @@
+```@meta
+DocTestSetup = quote
+    using StatsBase
+end
+```
 # Weight Vectors
 
 In statistical applications, it is not uncommon to assign weights to samples. To facilitate the use of weight vectors, we introduce the abstract type `AbstractWeights` for the purpose of representing weight vectors, which has two advantages:
@@ -68,40 +73,42 @@ weights to past observations.
 
 If `t` is a vector of temporal indices then for each index `i` we compute the weight as:
 
-``λ (1 - λ)^{1 - i}``
+```math
+λ (1 - λ)^{1 - i}
+```
 
 ``λ`` is a smoothing factor or rate parameter such that ``0 < λ ≤ 1``.
 As this value approaches 0, the resulting weights will be almost equal,
 while values closer to 1 will put greater weight on the tail elements of the vector.
 
 For example, the following call generates exponential weights for ten observations with ``λ = 0.3``.
-```julia-repl
+```jldoctest
 julia> eweights(1:10, 0.3)
-10-element Weights{Float64,Float64,Array{Float64,1}}:
+10-element Weights{Float64, Float64, Vector{Float64}}:
  0.3
  0.42857142857142855
  0.6122448979591837
  0.8746355685131197
  1.249479383590171
  1.7849705479859588
- 2.549957925694227
+ 2.5499579256942266
  3.642797036706039
  5.203995766722913
  7.434279666747019
 ```
 
 Simply passing the number of observations `n` is equivalent to passing in `1:n`.
 
-```julia-repl
+```jldoctest
 julia> eweights(10, 0.3)
-10-element Weights{Float64,Float64,Array{Float64,1}}:
+10-element Weights{Float64, Float64, Vector{Float64}}:
  0.3
  0.42857142857142855
  0.6122448979591837
  0.8746355685131197
  1.249479383590171
  1.7849705479859588
- 2.549957925694227
+ 2.5499579256942266
  3.642797036706039
  5.203995766722913
  7.434279666747019
@@ -117,25 +124,24 @@ julia> r
 2019-01-01T01:00:00:1 hour:2019-01-02T01:00:00
 
 julia> eweights(t, r, 0.3)
-3-element Weights{Float64,Float64,Array{Float64,1}}:
+3-element Weights{Float64, Float64, Vector{Float64}}:
  0.3
  0.6122448979591837
  1.249479383590171
 ```
 
-NOTE: This is equivalent to `eweights(something.(indexin(t, r)), 0.3)`, which is saying that for each value in `t` return the corresponding index for that value in `r`.
-Since `indexin` returns `nothing` if there is no corresponding value from `t` in `r` we use `something` to eliminate that possibility.
+!!! note
+    This is equivalent to `eweights(something.(indexin(t, r)), 0.3)`, which is saying that for each value in `t` return the corresponding index for that value in `r`.
+    Since `indexin` returns `nothing` if there is no corresponding value from `t` in `r` we use `something` to eliminate that possibility.
 
 ## Methods
 
 `AbstractWeights` implements the following methods:
-```
-eltype
-length
-isempty
-values
-sum
-```
+- `eltype`
+- `length`
+- `isempty`
+- `values`
+- `sum`
 
 The following constructors are provided:
 ```@docs

src/cov.jl

@@ -188,7 +188,8 @@ cov(ce::CovarianceEstimator, x::AbstractVector, y::AbstractVector) =
     error("cov is not defined for $(typeof(ce)), $(typeof(x)) and $(typeof(y))")
 
 """
-    cov(ce::CovarianceEstimator, X::AbstractMatrix, [w::AbstractWeights]; mean=nothing, dims::Int=1)
+    cov(ce::CovarianceEstimator, X::AbstractMatrix, [w::AbstractWeights];
+        mean=nothing, dims::Int=1)
 
 Compute the covariance matrix of the matrix `X` along dimension `dims`
 using estimator `ce`. A weighting vector `w` can be specified.
@@ -238,10 +239,8 @@ function cor(ce::CovarianceEstimator, x::AbstractVector, y::AbstractVector)
 end
 
 """
-    cor(
-        ce::CovarianceEstimator, X::AbstractMatrix, [w::AbstractWeights];
-        mean=nothing, dims::Int=1
-    )
+    cor(ce::CovarianceEstimator, X::AbstractMatrix, [w::AbstractWeights];
+        mean=nothing, dims::Int=1)
 
 Compute the correlation matrix of the matrix `X` along dimension `dims`
 using estimator `ce`. A weighting vector `w` can be specified.

src/deviation.jl

@@ -90,7 +90,7 @@ end
     Linfdist(a, b)
 
 Compute the L∞ distance, also called the Chebyshev distance, between
-two arrays: ``\\max_{i\\in1:n} |a_i - b_i|``.
+two arrays: ``\\max_{1≤i≤n} |a_i - b_i|``.
 Efficient equivalent of `maxabs(a - b)`.
 """
 function Linfdist(a::AbstractArray{T}, b::AbstractArray{T}) where T<:Number

src/hist.jl

@@ -155,15 +155,15 @@ closed: right
 isdensity: false
 ```
 ## Example illustrating `isdensity`
-```julia
+```jldoctest
 julia> using StatsBase, LinearAlgebra
 
 julia> bins = [0,1,7]; # a small and a large bin
 
 julia> obs = [0.5, 1.5, 1.5, 2.5]; # one observation in the small bin and three in the large
 
 julia> h = fit(Histogram, obs, bins)
-Histogram{Int64,1,Tuple{Array{Int64,1}}}
+Histogram{Int64, 1, Tuple{Vector{Int64}}}
 edges:
   [0, 1, 7]
 weights: [1, 3]
@@ -173,7 +173,7 @@ isdensity: false
 julia> # observe isdensity = false and the weights field records the number of observations in each bin
 
 julia> normalize(h, mode=:density)
-Histogram{Float64,1,Tuple{Array{Int64,1}}}
+Histogram{Float64, 1, Tuple{Vector{Int64}}}
 edges:
   [0, 1, 7]
 weights: [1.0, 0.5]
@@ -459,7 +459,8 @@ float(h::Histogram{T,N}) where {T,N} = Histogram(h.edges, float(h.weights), h.cl
 
 
 """
-    normalize!(h::Histogram{T,N}, aux_weights::Array{T,N}...; mode::Symbol=:pdf) where {T<:AbstractFloat,N}
+    normalize!(h::Histogram{T,N}, aux_weights::Array{T,N}...;
+               mode::Symbol=:pdf) where {T<:AbstractFloat,N}
 
 Normalize the histogram `h` and optionally scale one or more auxiliary weight
 arrays appropriately. See description of `normalize` for details. Returns `h`.

src/reliability.jl

@@ -19,11 +19,11 @@ Calculate Cronbach's alpha (1951) from a covariance matrix `covmatrix` according
 the [formula](https://en.wikipedia.org/wiki/Cronbach%27s_alpha):
 
 ```math
-\\rho = \\frac{k}{k-1} (1 - \\frac{\\sum^k_{i=1} \\sigma^2_i}{\\sum_{i=1}^k \\sum_{j=1}^k \\sigma_{ij}})
+ρ = \\frac{k}{k-1} \\left(1 - \\frac{\\sum^k_{i=1} σ^2_i}{\\sum_{i=1}^k \\sum_{j=1}^k σ_{ij}}\\right)
 ```
 
-where ``k`` is the number of items, i.e. columns, ``\\sigma_i^2`` the item variance,
-and ``\\sigma_{ij}`` the inter-item covariance.
+where ``k`` is the number of items, i.e. columns, ``σ_i^2`` the item variance,
+and ``σ_{ij}`` the inter-item covariance.
 
 Returns a `CronbachAlpha` object that holds:
 

src/robust.jl

@@ -41,9 +41,9 @@ To compute the trimmed mean of `x` use `mean(trim(x))`;
 to compute the variance use `trimvar(x)` (see [`trimvar`](@ref)).
 
 # Example
-```julia
+```jldoctest
 julia> collect(trim([5,2,4,3,1], prop=0.2))
-3-element Array{Int64,1}:
+3-element Vector{Int64}:
  2
  4
  3
@@ -80,9 +80,9 @@ elements equal the lower or upper bound.
 To compute the Winsorized mean of `x` use `mean(winsor(x))`.
 
 # Example
-```julia
+```jldoctest
 julia> collect(winsor([5,2,3,4,1], prop=0.2))
-5-element Array{Int64,1}:
+5-element Vector{Int64}:
  4
  2
  3

src/sampling.jl

@@ -188,7 +188,7 @@ knuths_sample!(a::AbstractArray, x::AbstractArray; initshuffle::Bool=true) =
 Fisher-Yates shuffling (with early termination).
 
 Pseudo-code:
-```
+```julia
 n = length(a)
 k = length(x)