Doc fixes (#1266)

* README.md: improve guidance on local documentation build

* Fix aligned equations in documentation

* Add index to doc pages with many methods

* Fix broken doc references

* Fix doctests

* Re-enable doctests in CI

.github/workflows/ci.yml

@@ -63,11 +63,11 @@ jobs:
             using Pkg
             Pkg.develop(PackageSpec(path=pwd()))
             Pkg.instantiate()'
-      # - run: |
-      #     julia --project=docs -e '
-      #       using Documenter: doctest
-      #       using Distributions
-      #       doctest(Distributions)'
+      - run: |
+          julia --project=docs -e '
+            using Documenter: doctest
+            using Distributions
+            doctest(Distributions)'
       - run: julia --project=docs docs/make.jl
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

README.md

@@ -61,7 +61,13 @@ the following are required for contributions to be accepted:
 1. Docstrings must be added to all interface and non-trivial functions.
 2. Tests validating the modified behavior in the `test` folder. If new test files are added, do not forget to add them in `test/runtests.jl`. Cover possible edge cases. Run the tests locally before submitting the PR.
 3. At the end of the tests, `Test.detect_ambiguities(Distributions)` is run to check method ambiguities. Verify that your modified code did not yield method ambiguities.
-4. Make according modifications to the `docs` folder, build the documentation locally with `$ julia docs/make.jl`, verify that your modifications display correctly and did not yield warnings.
+4. Make according modifications to the `docs` folder, build the documentation locally and verify that your modifications display correctly and did not yield warnings. To build the documentation locally, you first need to instantiate the `docs/` project:
+
+       julia --project=docs/
+       pkg> instantiate
+       pkg> dev .
+
+   Then use `julia --project=docs/ docs/make.jl` to build the documentation.
 
 ## Citing
 

docs/src/matrix.md

@@ -47,3 +47,9 @@ LKJ
 ```@docs
 Distributions._logpdf(d::MatrixDistribution, x::AbstractArray)
 ```
+
+## Index
+
+```@index
+Pages = ["matrix.md"]
+```

docs/src/multivariate.md

@@ -33,7 +33,7 @@ entropy(::MultivariateDistribution, ::Real)
 insupport(::MultivariateDistribution, ::AbstractArray)
 pdf(::MultivariateDistribution, ::AbstractArray)
 logpdf(::MultivariateDistribution, ::AbstractArray)
-loglikelihood(::MultivariateDistribution, ::AbstractArray)
+loglikelihood(::MultivariateDistribution, ::AbstractVector{<:Real})
 ```
 **Note:** For multivariate distributions, the pdf value is usually very small or large, and therefore direct evaluating the pdf may cause numerical problems. It is generally advisable to perform probability computation in log-scale.
 
@@ -108,3 +108,9 @@ Distributions.product_distribution
 
 Using `product_distribution` is advised to construct product distributions. 
 For some distributions, it constructs a special multivariate type.
+
+## Index
+
+```@index
+Pages = ["multivariate.md"]
+```

docs/src/univariate.md

@@ -71,10 +71,10 @@ cf(::UnivariateDistribution, ::Any)
 insupport(::UnivariateDistribution, x::Any)
 pdf(::UnivariateDistribution, ::Real)
 logpdf(::UnivariateDistribution, ::Real)
-loglikelihood(::UnivariateDistribution, ::Union{Real,AbstractArray})
+loglikelihood(::UnivariateDistribution, ::AbstractArray)
 cdf(::UnivariateDistribution, ::Real)
 logcdf(::UnivariateDistribution, ::Real)
-logdiffcdf(::UnivariateDistribution, ::T, ::T) where {T <: Real}
+logdiffcdf(::UnivariateDistribution, ::Real, ::Real)
 ccdf(::UnivariateDistribution, ::Real)
 logccdf(::UnivariateDistribution, ::Real)
 quantile(::UnivariateDistribution, ::Real)
@@ -162,3 +162,9 @@ Skellam
 ### Vectorized evaluation
 
 Vectorized computation and inplace vectorized computation have been deprecated.
+
+## Index
+
+```@index
+Pages = ["univariate.md"]
+```

src/matrix/matrixfdist.jl

@@ -21,10 +21,10 @@ If the joint distribution ``p(\\boldsymbol{\\Psi},\\boldsymbol{\\Sigma})=p(\\bol
 is given by
 
 ```math
-\\begin{align*}
+\\begin{aligned}
 \\boldsymbol{\\Psi}&\\sim \\textrm{W}_p(n_1, \\mathbf{B})\\\\
 \\boldsymbol{\\Sigma}|\\boldsymbol{\\Psi}&\\sim \\textrm{IW}_p(n_2, \\boldsymbol{\\Psi}),
-\\end{align*}
+\\end{aligned}
 ```
 
 then the marginal distribution of ``\\boldsymbol{\\Sigma}`` is

src/matrix/matrixtdist.jl

@@ -26,10 +26,10 @@ If the joint distribution ``p(\\mathbf{S},\\mathbf{X})=p(\\mathbf{S})p(\\mathbf{
 is given by
 
 ```math
-\\begin{align*}
+\\begin{aligned}
 \\mathbf{S}&\\sim \\textrm{IW}_n(\\nu + n - 1, \\boldsymbol{\\Sigma})\\\\
 \\mathbf{X}|\\mathbf{S}&\\sim \\textrm{MN}_{n,p}(\\mathbf{M}, \\mathbf{S}, \\boldsymbol{\\Omega}),
-\\end{align*}
+\\end{aligned}
 ```
 
 then the marginal distribution of ``\\mathbf{X}`` is

src/univariate/continuous/studentizedrange.jl

@@ -11,10 +11,10 @@ f(q; k, \\nu) = \\frac{\\sqrt{2\\pi}k(k - 1)\\nu^{\\nu/2}}{\\Gamma{\\left(\\frac
 where
 
 ```math
-\\begin{align*}
+\\begin{aligned}
 \\Phi(x) &= \\frac{1 + erf(\\frac{x}{\\sqrt{2}})}{2} &&(\\text{Normal Distribution CDF})\\\\
 \\phi(x) &= \\Phi'(x) &&(\\text{Normal Distribution PDF})
-\\end{align*}
+\\end{aligned}
 ```
 
 ```julia

src/utils.jl

@@ -70,7 +70,7 @@ end
 Test whether a matrix is positive semi-definite with specified rank `k` by
 checking that `k` of its eigenvalues are positive and the rest are zero.
 # Examples
-```jldoctest
+```jldoctest; setup = :(using Distributions: ispossemdef)
 julia> A = [1 0; 0 0]
 2×2 Array{Int64,2}:
  1  0