Add docs interlinks (#131)

* Add DocumenterInterLinks as docs dependency * Add docs interlinks * Add external references to methods * Use interlinking to link to MLJ docs * Increment patch number
TuringLang · Dec 5, 2024 · 438da79 · 438da79 · sethaxen · Dec 5, 2024
1 parent 9d3e4ca
commit 438da79
Show file tree

Hide file tree

Showing 6 changed files with 26 additions and 11 deletions.
diff --git a/Project.toml b/Project.toml
@@ -1,7 +1,7 @@
 name = "MCMCDiagnosticTools"
 uuid = "be115224-59cd-429b-ad48-344e309966f0"
 authors = ["David Widmann", "Seth Axen"]
-version = "0.3.12"
+version = "0.3.13"
 
 [deps]
 AbstractFFTs = "621f4979-c628-5d54-868e-fcf4e3e8185c"

diff --git a/docs/Project.toml b/docs/Project.toml
@@ -1,5 +1,6 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterInterLinks = "d12716ef-a0f6-4df4-a9f1-a5a34e75c656"
 EvoTrees = "f6006082-12f8-11e9-0c9c-0d5d367ab1e5"
 MLJBase = "a7f614a8-145f-11e9-1d2a-a57a1082229d"
 MLJIteration = "614be32b-d00c-4edb-bd02-1eb411ab5e55"
@@ -9,6 +10,7 @@ Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 
 [compat]
 Documenter = "1"
+DocumenterInterLinks = "1"
 EvoTrees = "0.15, 0.16"
 MLJBase = "0.20, 0.21, 1"
 MLJIteration = "0.5, 0.6"

diff --git a/docs/make.jl b/docs/make.jl
@@ -1,4 +1,5 @@
 using Documenter
+using DocumenterInterLinks
 
 # Print `@debug` statements (https://github.com/JuliaDocs/Documenter.jl/issues/955)
 if haskey(ENV, "GITHUB_ACTIONS")
@@ -11,6 +12,15 @@ DocMeta.setdocmeta!(
     MCMCDiagnosticTools, :DocTestSetup, :(using MCMCDiagnosticTools); recursive=true
 )
 
+links = InterLinks(
+    "MLJ" => "https://juliaai.github.io/MLJ.jl/stable/",
+    "Statistics" => "https://docs.julialang.org/en/v1/",
+    "StatsBase" => (
+        "https://juliastats.org/StatsBase.jl/stable/",
+        "https://juliastats.org/StatsBase.jl/dev/objects.inv",
+    ),
+)
+
 makedocs(;
     modules=[MCMCDiagnosticTools],
     authors="David Widmann",
@@ -24,6 +34,7 @@ makedocs(;
     pages=["Home" => "index.md"],
     warnonly=:footnote,
     checkdocs=:exports,
+    plugins=[links],
 )
 
 deploydocs(;

diff --git a/src/ess_rhat.jl b/src/ess_rhat.jl
@@ -248,10 +248,10 @@ If `kind` isa a `Symbol`, it may take one of the following values:
     distributed. This transform is monotonic.
 
 Otherwise, `kind` specifies one of the following estimators, whose ESS is to be estimated:
-- `Statistics.mean`
-- `Statistics.median`
-- `Statistics.std`
-- `StatsBase.mad`
+- [`Statistics.mean`](@extref)
+- [`Statistics.median`](@extref)
+- [`Statistics.std`](@extref)
+- [`StatsBase.mad`](@extref)
 - `Base.Fix2(Statistics.quantile, p::Real)`
 
 [^VehtariGelman2021]: Vehtari, A., Gelman, A., Simpson, D., Carpenter, B., & Bürkner, P. C. (2021).

diff --git a/src/mcse.jl b/src/mcse.jl
@@ -17,9 +17,9 @@ vector of the same `eltype` as `samples` and return a real estimate.
 For the following estimators, the effective sample size [`ess`](@ref) and an estimate
 of the asymptotic variance are used to compute the MCSE, and `kwargs` are forwarded to
 `ess`:
-- `Statistics.mean`
-- `Statistics.median`
-- `Statistics.std`
+- [`Statistics.mean`](@extref)
+- [`Statistics.median`](@extref)
+- [`Statistics.std`](@extref)
 - `Base.Fix2(Statistics.quantile, p::Real)`
 
 For other estimators, the subsampling bootstrap method (SBM)[^FlegalJones2011][^Flegal2012]

diff --git a/src/rstar.jl b/src/rstar.jl
@@ -138,7 +138,7 @@ Compute the ``R^*`` convergence statistic of the `samples` with the `classifier`
 This implementation is an adaption of algorithms 1 and 2 described by Lambert and Vehtari.
 
 The `classifier` has to be a supervised classifier of the MLJ framework (see the
-[MLJ documentation](https://alan-turing-institute.github.io/MLJ.jl/dev/list_of_supported_models/#model_list)
+[MLJ documentation](@extref MLJ list_of_supported_models)
 for a list of supported models). It is trained with a `subset` of the samples from each
 chain. Each chain is split into `split_chains` separate chains to additionally check for
 within-chain convergence. The training of the classifier can be inspected by adjusting the
@@ -175,7 +175,8 @@ julia> round(mean(distribution); digits=2)
 ```
 
 Note, however, that it is recommended to determine `nrounds` based on early-stopping.
-With the MLJ framework, this can be achieved in the following way (see the [MLJ documentation](https://alan-turing-institute.github.io/MLJ.jl/dev/controlling_iterative_models/) for additional explanations):
+With the MLJ framework, this can be achieved in the following way (see the
+[MLJ documentation](@extref MLJ Controlling-Iterative-Models) for additional explanations):
 
 ```jldoctest rstar
 julia> model = IteratedModel(;
@@ -195,7 +196,8 @@ julia> round(mean(distribution); digits=2)
 
 For deterministic classifiers, a single ``R^*`` statistic (algorithm 1) is returned.
 Deterministic classifiers can also be derived from probabilistic classifiers by e.g.
-predicting the mode. In MLJ this corresponds to a pipeline of models.
+predicting the mode. In MLJ this corresponds to a [pipeline](@extref MLJ Pipeline_MLJBase)
+of models.
 
 ```jldoctest rstar
 julia> evotree_deterministic = Pipeline(model; operation=predict_mode);