Add docs interlinks (#42)

* Add DocumenterInterLinks as docs dependency

* Add minimal TOML inventory for IntervalSets

* Create docs interlinks

* Add external links

* Add docs previews

* Create DocsPreviewCleanup.yml

* Fix directive to build preview docs

.github/workflows/DocsPreviewCleanup.yml

@@ -0,0 +1,26 @@
+name: DocsPreviewCleanup
+
+on:
+  pull_request:
+    types: [closed]
+
+jobs:
+  cleanup:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout gh-pages branch
+        uses: actions/checkout@v4
+        with:
+          ref: gh-pages
+      - name: Delete preview and history + push changes
+        run: |
+            if [ -d "previews/PR$PRNUM" ]; then
+              git config user.name "Documenter.jl"
+              git config user.email "[email protected]"
+              git rm -rf "previews/PR$PRNUM"
+              git commit -m "delete preview"
+              git branch gh-pages-new $(echo "delete history" | git commit-tree HEAD^{tree})
+              git push --force origin gh-pages-new:gh-pages
+            fi
+        env:
+            PRNUM: ${{ github.event.number }}

docs/Project.toml

@@ -1,10 +1,12 @@
 [deps]
 ArviZExampleData = "2f96bb34-afd9-46ae-bcd0-9b2d4372fe3c"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterInterLinks = "d12716ef-a0f6-4df4-a9f1-a5a34e75c656"
 MCMCDiagnosticTools = "be115224-59cd-429b-ad48-344e309966f0"
 PosteriorStats = "7f36be82-ad55-44ba-a5c0-b8b5480d7aa5"
 Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
 
 [compat]
 Documenter = "1"
+DocumenterInterLinks = "1"

docs/inventories/IntervalSets.toml

@@ -0,0 +1,8 @@
+# DocInventory version 1
+project = "IntervalSets.jl"
+version = "0.7.10"
+
+# NOTE: trimmed to just the API functions we link to
+[[jl.type]]
+name = "IntervalSets.ClosedInterval"
+uri = "api/#$"

docs/make.jl

@@ -1,8 +1,23 @@
 using PosteriorStats
 using Documenter
+using DocumenterInterLinks
 
 DocMeta.setdocmeta!(PosteriorStats, :DocTestSetup, :(using PosteriorStats); recursive=true)
 
+links = InterLinks(
+    "IntervalSets" => (
+        "https://juliamath.github.io/IntervalSets.jl/stable/",
+        joinpath(@__DIR__, "inventories", "IntervalSets.toml"),
+    ),
+    "MCMCDiagnosticTools" => "https://julia.arviz.org/MCMCDiagnosticTools/stable/",
+    "PSIS" => "https://julia.arviz.org/PSIS/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=[PosteriorStats],
     repo=Remotes.GitHub("arviz-devs", "PosteriorStats.jl"),
@@ -12,6 +27,9 @@ makedocs(;
     ),
     pages=["Home" => "index.md", "API" => "api.md"],
     warnonly=[:footnote, :missing_docs],
+    plugins=[links],
 )
 
-deploydocs(; repo="github.com/arviz-devs/PosteriorStats.jl.git", devbranch="main")
+deploydocs(;
+    repo="github.com/arviz-devs/PosteriorStats.jl.git", devbranch="main", push_preview=true
+)

src/eti.jl

@@ -6,7 +6,8 @@ Estimate the equal-tailed interval (ETI) of `samples` for the probability `prob`
 
 The ETI of a given probability is the credible interval wih the property that the
 probability of being below the interval is equal to the probability of being above it.
-That is, it is defined by the `(1-prob)/2` and `1 - (1-prob)/2` quantiles of the samples.
+That is, it is defined by the `(1-prob)/2` and `1 - (1-prob)/2`
+[quantiles](@extref `Statistics.quantile`) of the samples.
 
 See also: [`eti!`](@ref), [`hdi`](@ref), [`hdi!`](@ref).
 
@@ -17,11 +18,11 @@ See also: [`eti!`](@ref), [`hdi`](@ref), [`hdi!`](@ref).
 # Keywords
 - `prob`: the probability mass to be contained in the ETI. Default is
     `$(DEFAULT_INTERVAL_PROB)`.
-- `kwargs`: remaining keywords are passed to `Statistics.quantile`.
+- `kwargs`: remaining keywords are passed to [`Statistics.quantile`](@extref).
 
 # Returns
 - `intervals`: If `samples` is a vector or matrix, then a single
-    `IntervalSets.ClosedInterval` is returned. Otherwise, an array with the shape
+    [`IntervalSets.ClosedInterval`](@extref) is returned. Otherwise, an array with the shape
     `(params...,)`, is returned, containing a marginal ETI for each parameter.
 
 !!! note

src/hdi.jl

@@ -113,9 +113,9 @@ See also: [`hdi!`](@ref), [`eti`](@ref), [`eti!`](@ref).
 
 # Returns
 - `intervals`: If `samples` is a vector or matrix, then a single
-    `IntervalSets.ClosedInterval` is returned for `:unimodal` method, or a vector of
-    `IntervalSets.ClosedInterval` for multimodal methods. For higher dimensional inputs,
-    an array with the shape `(params...,)` is returned, containing marginal HDIs for each parameter.
+    [`IntervalSets.ClosedInterval`](@extref) is returned for `:unimodal` method, or a vector
+    of `ClosedInterval` for multimodal methods. For higher dimensional inputs, an array with
+    the shape `(params...,)` is returned, containing marginal HDIs for each parameter.
 
 !!! note
     Any default value of `prob` is arbitrary. The default value of

src/loo.jl

@@ -12,7 +12,7 @@ struct PSISLOOResult{E,P,R<:PSIS.PSISResult} <: AbstractELPDResult
     estimates::E
     "Pointwise estimates"
     pointwise::P
-    "Pareto-smoothed importance sampling (PSIS) results"
+    "A [`PSIS.PSISResult`](@extref) with Pareto-smoothed importance sampling (PSIS) results"
     psis_result::R
 end
 
@@ -43,8 +43,8 @@ Compute the Pareto-smoothed importance sampling leave-one-out cross-validation (
   - `reff::Union{Real,AbstractArray{<:Real}}`: The relative effective sample size(s) of the
     _likelihood_ values. If an array, it must have the same data dimensions as the
     corresponding log-likelihood variable. If not provided, then this is estimated using
-    `MCMCDiagnosticTools.ess`.
-  - `kwargs`: Remaining keywords are forwarded to [`PSIS.psis`].
+    [`MCMCDiagnosticTools.ess`](@extref).
+  - `kwargs`: Remaining keywords are forwarded to [`PSIS.psis`](@extref).
 
 See also: [`PSISLOOResult`](@ref), [`waic`](@ref)
 

src/summarize.jl

@@ -184,7 +184,8 @@ See also [`SummaryStats`](@ref), [`default_summary_stats`](@ref), [`default_stat
 
 # Examples
 
-Compute `mean`, `std` and the Monte Carlo standard error (MCSE) of the mean estimate:
+Compute [`Statistics.mean`](@extref), [`Statistics.std`](@extref) and the Monte Carlo
+standard error (MCSE) of the mean estimate:
 
 ```jldoctest summarize; setup = (using Random; Random.seed!(84))
 julia> using Statistics, StatsBase
@@ -199,7 +200,8 @@ Mean/Std
  3  19.98    0.988      0.016
 ```
 
-Avoid recomputing the mean by using `mean_and_std`, and provide parameter names:
+Avoid recomputing the mean by using [`StatsBase.mean_and_std`](@extref), and provide
+parameter names:
 ```jldoctest summarize
 julia> summarize(x, (:mean, :std) => mean_and_std, mad; var_names=[:a, :b, :c])
 SummaryStats
@@ -234,7 +236,7 @@ SummaryStats
  c  20.0       0.988   18.5 .. 21.6
 ```
 
-Compute the summary stats focusing on `Statistics.median`:
+Compute the summary stats focusing on [`Statistics.median`](@extref):
 
 ```jldoctest summarize
 julia> summarize(x, default_summary_stats(median)...; var_names=[:a, :b, :c])
@@ -245,7 +247,7 @@ SummaryStats
  c  19.99   0.979   18.1 .. 21.9        0.020      3892        3829  1.00
 ```
 
-Compute multiple quantiles simultaneously:
+Compute multiple [quantiles](@extref `Statistics.quantile`) simultaneously:
 
 ```jldoctest summarize
 julia> qs = (0.05, 0.25, 0.5, 0.75, 0.95);
@@ -313,8 +315,8 @@ end
 Default statistics to be computed with [`summarize`](@ref).
 
 The value of `focus` determines the statistics to be returned:
-- `Statistics.mean`: `mean`, `std`, `hdi_94%`
-- `Statistics.median`: `median`, `mad`, `eti_94%`
+- [`Statistics.mean`](@extref): `mean`, [`std`](@extref `Statistics.std`), `hdi_94%`
+- [`Statistics.median`](@extref): `median`, [`mad`](@extref `StatsBase.mad`), `eti_94%`
 
 If `prob_interval` is set to a different value than the default, then different HDI and ETI
 statistics are computed accordingly. [`hdi`](@ref) refers to the highest-density interval,
@@ -352,8 +354,8 @@ end
 Default diagnostics to be computed with [`summarize`](@ref).
 
 The value of `focus` determines the diagnostics to be returned:
-- `Statistics.mean`: `mcse_mean`, `mcse_std`, `ess_tail`, `ess_bulk`, `rhat`
-- `Statistics.median`: `mcse_median`, `ess_tail`, `ess_bulk`, `rhat`
+- [`Statistics.mean`](@extref): `mcse_mean`, `mcse_std`, `ess_tail`, `ess_bulk`, `rhat`
+- [`Statistics.median`](@extref): `mcse_median`, `ess_tail`, `ess_bulk`, `rhat`
 """
 default_diagnostics(; kwargs...) = default_diagnostics(Statistics.mean; kwargs...)
 function default_diagnostics(::typeof(Statistics.mean); kwargs...)