From 2b7520ba9e346e7d287173275aa00a2539c0ab73 Mon Sep 17 00:00:00 2001 From: Seth Axen Date: Sat, 14 Dec 2024 15:18:59 +0100 Subject: [PATCH] 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 | 26 ++++++++++++++++++++++++ docs/Project.toml | 2 ++ docs/inventories/IntervalSets.toml | 8 ++++++++ docs/make.jl | 20 +++++++++++++++++- src/eti.jl | 7 ++++--- src/hdi.jl | 6 +++--- src/loo.jl | 6 +++--- src/summarize.jl | 18 ++++++++-------- 8 files changed, 75 insertions(+), 18 deletions(-) create mode 100644 .github/workflows/DocsPreviewCleanup.yml create mode 100644 docs/inventories/IntervalSets.toml diff --git a/.github/workflows/DocsPreviewCleanup.yml b/.github/workflows/DocsPreviewCleanup.yml new file mode 100644 index 0000000..c5c8c8c --- /dev/null +++ b/.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 "documenter@juliadocs.github.io" + 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 }} diff --git a/docs/Project.toml b/docs/Project.toml index 26b7eb3..c7b4678 100644 --- a/docs/Project.toml +++ b/docs/Project.toml @@ -1,6 +1,7 @@ [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" @@ -8,3 +9,4 @@ StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91" [compat] Documenter = "1" +DocumenterInterLinks = "1" diff --git a/docs/inventories/IntervalSets.toml b/docs/inventories/IntervalSets.toml new file mode 100644 index 0000000..3e0a400 --- /dev/null +++ b/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/#$" diff --git a/docs/make.jl b/docs/make.jl index 842640a..a46e36d 100644 --- a/docs/make.jl +++ b/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 +) diff --git a/src/eti.jl b/src/eti.jl index 0e974c9..b582f1d 100644 --- a/src/eti.jl +++ b/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 diff --git a/src/hdi.jl b/src/hdi.jl index 91aef5b..131c4dc 100644 --- a/src/hdi.jl +++ b/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 diff --git a/src/loo.jl b/src/loo.jl index 657d292..19ed242 100644 --- a/src/loo.jl +++ b/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) diff --git a/src/summarize.jl b/src/summarize.jl index d59dc87..bdb7bba 100644 --- a/src/summarize.jl +++ b/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...)