Add docs interlinks (#91)

sethaxen · web-flow · commit fbbcfe8b8188 · 2024-12-14T23:28:42.000+01:00
* Fix doctests

* Add interlinks to referenced packages

* Import/export extended functions

* Link extended methods to original

* Add more links

* Remove outdated docstring

* Add extension docs pages

* Increment patch number

* Build preview docs

* Add minimal inventories for DimensionalData and IntervalSets

* Add more links to inventories

* Add links to DimensionalData pages

* Link to the InferenceData schema

* Link to IntervalSets
diff --git a/Project.toml b/Project.toml
@@ -1,7 +1,7 @@
 name = "InferenceObjects"
 uuid = "b5cf5a8d-e756-4ee3-b014-01d49d192c00"
 authors = ["Seth Axen <seth.axen@gmail.com> and contributors"]
-version = "0.4.7"
+version = "0.4.8"
 
 [deps]
 Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
diff --git 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"
 InferenceObjects = "b5cf5a8d-e756-4ee3-b014-01d49d192c00"
 MCMCDiagnosticTools = "be115224-59cd-429b-ad48-344e309966f0"
 NCDatasets = "85f8d34a-cbdd-5861-8df4-14fed0d494ab"
@@ -9,3 +10,4 @@ StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
 
 [compat]
 Documenter = "1"
+DocumenterInterLinks = "1"
diff --git a/docs/inventories/DimensionalData.toml b/docs/inventories/DimensionalData.toml
@@ -0,0 +1,14 @@
+# DocInventory version 1
+project = "DimensionalData.jl"
+version = "0.29.4"
+
+# NOTE: trimmed to just the pages we link to
+[[std.doc]]
+dispname = "Selectors"
+name = "selectors"
+uri = "selectors"
+
+[[std.doc]]
+dispname = "DimStacks"
+name = "dimstacks"
+uri = "stacks"
diff --git a/docs/inventories/IntervalSets.toml 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.AbstractInterval"
+uri = "api/#$"
diff --git a/docs/make.jl b/docs/make.jl
@@ -1,17 +1,40 @@
 using InferenceObjects
 using Documenter
+using DocumenterInterLinks
+using MCMCDiagnosticTools: MCMCDiagnosticTools  # load extension
 using NCDatasets: NCDatasets  # load extension
+using PosteriorStats: PosteriorStats  # load extension
+using StatsBase: StatsBase  # load extension
 
 DocMeta.setdocmeta!(
     InferenceObjects, :DocTestSetup, :(using InferenceObjects); recursive=true
 )
 
+links = InterLinks(
+    "arviz" => "https://python.arviz.org/en/stable/",
+    "DimensionalData" => (
+        "https://rafaqz.github.io/DimensionalData.jl/stable/",
+        joinpath(@__DIR__, "inventories", "DimensionalData.toml"),
+    ),
+    "IntervalSets" => (
+        "https://juliamath.github.io/IntervalSets.jl/stable/",
+        joinpath(@__DIR__, "inventories", "IntervalSets.toml"),
+    ),
+    "NCDatasets" => "https://alexander-barth.github.io/NCDatasets.jl/stable/",
+    "PosteriorStats" => "https://julia.arviz.org/PosteriorStats/stable/",
+    "MCMCDiagnosticTools" => "https://julia.arviz.org/MCMCDiagnosticTools/stable/",
+)
+
 doctestfilters = [
     r"\s+\"created_at\" => .*",  # ignore timestamps in doctests
 ]
 
 makedocs(;
-    modules=[InferenceObjects],
+    modules=[
+        InferenceObjects,
+        Base.get_extension(InferenceObjects, :InferenceObjectsMCMCDiagnosticToolsExt),
+        Base.get_extension(InferenceObjects, :InferenceObjectsPosteriorStatsExt),
+    ],
     authors="Seth Axen <seth.axen@gmail.com> and contributors",
     repo=Remotes.GitHub("arviz-devs", "InferenceObjects.jl"),
     sitename="InferenceObjects.jl",
@@ -25,9 +48,14 @@ makedocs(;
         "Home" => "index.md",
         "Dataset" => "dataset.md",
         "InferenceData" => "inference_data.md",
+        "Extensions" => [
+            "MCMCDiagnosticTools" => "extensions/mcmcdiagnostictools.md",
+            "PosteriorStats" => "extensions/posteriorstats.md",
+        ],
     ],
     doctestfilters=doctestfilters,
     warnonly=:missing_docs,
+    plugins=[links],
 )
 
 # run doctests on extensions
@@ -49,4 +77,6 @@ for extended_pkg in (MCMCDiagnosticTools, PosteriorStats)
     doctest(mod; manual=false)
 end
 
-deploydocs(; repo="github.com/arviz-devs/InferenceObjects.jl", devbranch="main")
+deploydocs(;
+    repo="github.com/arviz-devs/InferenceObjects.jl", devbranch="main", push_preview=true
+)
diff --git a/docs/src/dataset.md b/docs/src/dataset.md
@@ -20,7 +20,7 @@ namedtuple_to_dataset
 ## DimensionalData
 
 As a `DimensionalData.AbstractDimStack`, `Dataset` also implements the `AbstractDimStack` API and can be used like a `DimStack`.
-See [DimensionalData's documentation](https://rafaqz.github.io/DimensionalData.jl/stable/) for example usage.
+See [DimensionalData's documentation](@extref DimensionalData dimstacks) for example usage.
 
 ## Tables inteface
 
diff --git a/docs/src/extensions/mcmcdiagnostictools.md b/docs/src/extensions/mcmcdiagnostictools.md
@@ -0,0 +1,12 @@
+# Extension of MCMCDiagnosticTools
+
+The following methods of [MCMCDiagnosticTools.jl](https://julia.arviz.org/MCMCDiagnosticTools) are extended by this package.
+
+```@index
+Modules = [MCMCDiagnosticTools]
+```
+
+```@autodocs
+Modules = [Base.get_extension(InferenceObjects, :InferenceObjectsMCMCDiagnosticToolsExt)]
+Private = false
+```
diff --git a/docs/src/extensions/posteriorstats.md b/docs/src/extensions/posteriorstats.md
@@ -0,0 +1,16 @@
+# Extension of PosteriorStats
+
+The following methods of [PosteriorStats.jl](https://julia.arviz.org/PosteriorStats) are extended by this package.
+
+```@index
+Modules = [
+    Base.get_extension(InferenceObjects, :InferenceObjectsPosteriorStatsExt),
+    PosteriorStats,
+    StatsBase,
+]
+```
+
+```@autodocs
+Modules = [Base.get_extension(InferenceObjects, :InferenceObjectsPosteriorStatsExt)]
+Private = false
+```
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -4,7 +4,7 @@ CurrentModule = InferenceObjects
 
 # InferenceObjects
 
-InferenceObjects.jl is a Julia implementation of the [InferenceData schema](https://python.arviz.org/en/latest/schema/schema.html) for storing results of Bayesian inference.
+InferenceObjects.jl is a Julia implementation of the [InferenceData schema](@extref arviz schema) for storing results of Bayesian inference.
 Its purpose is to serve the following three goals:
 1. Usefulness in the analysis of Bayesian inference results.
 2. Reproducibility of Bayesian inference analysis.
diff --git a/ext/InferenceObjectsMCMCDiagnosticToolsExt/InferenceObjectsMCMCDiagnosticToolsExt.jl b/ext/InferenceObjectsMCMCDiagnosticToolsExt/InferenceObjectsMCMCDiagnosticToolsExt.jl
@@ -5,6 +5,10 @@ using DimensionalData: DimensionalData, Dimensions, LookupArrays
 using InferenceObjects: InferenceObjects, Random
 using MCMCDiagnosticTools: MCMCDiagnosticTools
 
+import MCMCDiagnosticTools: bfmi, ess_rhat, mcse, rstar
+
+export bfmi, ess_rhat, mcse, rstar
+
 maplayers = isdefined(DimensionalData, :maplayers) ? DimensionalData.maplayers : map
 
 include("utils.jl")
diff --git a/ext/InferenceObjectsMCMCDiagnosticToolsExt/bfmi.jl b/ext/InferenceObjectsMCMCDiagnosticToolsExt/bfmi.jl
@@ -3,6 +3,8 @@
     bfmi(sample_stats::Dataset) -> DimArray
 
 Calculate the chainwise estimated Bayesian fraction of missing information (BFMI).
+
+See [`MCMCDiagnosticTools.bfmi`](@extref) for more details.
 """
 function MCMCDiagnosticTools.bfmi(data::InferenceObjects.InferenceData)
     return MCMCDiagnosticTools.bfmi(data.sample_stats)
diff --git a/ext/InferenceObjectsMCMCDiagnosticToolsExt/ess_rhat.jl b/ext/InferenceObjectsMCMCDiagnosticToolsExt/ess_rhat.jl
@@ -3,6 +3,9 @@
     ess(data::Dataset; kwargs...) -> Dataset
 
 Calculate the effective sample size (ESS) for each parameter in the data.
+
+For more details and a description of the `kwargs`, see
+[`MCMCDiagnosticTools.ess`](@extref).
 """
 function MCMCDiagnosticTools.ess(data::InferenceObjects.InferenceData; kwargs...)
     return MCMCDiagnosticTools.ess(data.posterior; kwargs...)
@@ -13,6 +16,9 @@ end
     rhat(data::Dataset; kwargs...) -> Dataset
 
 Calculate the ``\\widehat{R}`` diagnostic for each parameter in the data.
+
+For more details and a description of the `kwargs`, see
+[`MCMCDiagnosticTools.rhat`](@extref).
 """
 function MCMCDiagnosticTools.rhat(data::InferenceObjects.InferenceData; kwargs...)
     return MCMCDiagnosticTools.rhat(data.posterior; kwargs...)
@@ -35,6 +41,9 @@ end
 
 Calculate the effective sample size (ESS) and ``\\widehat{R}`` diagnostic for each parameter
 in the data.
+
+For more details and a description of the `kwargs`, see
+[`MCMCDiagnosticTools.ess_rhat`](@extref).
 """
 function MCMCDiagnosticTools.ess_rhat(data::InferenceObjects.InferenceData; kwargs...)
     return MCMCDiagnosticTools.ess_rhat(data.posterior; kwargs...)
diff --git a/ext/InferenceObjectsMCMCDiagnosticToolsExt/mcse.jl b/ext/InferenceObjectsMCMCDiagnosticToolsExt/mcse.jl
@@ -3,6 +3,9 @@
     mcse(data::Dataset; kwargs...) -> Dataset
 
 Calculate the Monte Carlo standard error (MCSE) for each parameter in the data.
+
+For more details and a description of the `kwargs`, see
+[`MCMCDiagnosticTools.mcse`](@extref).
 """
 function MCMCDiagnosticTools.mcse(data::InferenceObjects.InferenceData; kwargs...)
     return MCMCDiagnosticTools.mcse(data.posterior; kwargs...)
diff --git a/ext/InferenceObjectsMCMCDiagnosticToolsExt/rstar.jl b/ext/InferenceObjectsMCMCDiagnosticToolsExt/rstar.jl
@@ -7,6 +7,9 @@
     )
 
 Calculate the ``R^*`` diagnostic for the data.
+
+For a description of the `classifier` and `kwargs`, see
+[`MCMCDiagnosticTools.rstar`](@extref).
 """
 function MCMCDiagnosticTools.rstar(
     rng::Random.AbstractRNG, clf, data::InferenceObjects.InferenceData; kwargs...
diff --git a/ext/InferenceObjectsPosteriorStatsExt/InferenceObjectsPosteriorStatsExt.jl b/ext/InferenceObjectsPosteriorStatsExt/InferenceObjectsPosteriorStatsExt.jl
@@ -6,6 +6,11 @@ using InferenceObjects: InferenceObjects
 using PosteriorStats: PosteriorStats
 using StatsBase: StatsBase
 
+import PosteriorStats: hdi, loo, loo_pit, r2_score, summarize, waic
+import StatsBase: summarystats
+
+export hdi, loo, loo_pit, r2_score, summarize, waic, summarystats
+
 include("utils.jl")
 include("hdi.jl")
 include("loo.jl")
diff --git a/ext/InferenceObjectsPosteriorStatsExt/hdi.jl b/ext/InferenceObjectsPosteriorStatsExt/hdi.jl
@@ -10,6 +10,8 @@ end
     hdi(data::Dataset; kwargs...) -> Dataset
 
 Calculate the highest density interval (HDI) for each parameter in the data.
+
+For more details and a description of the `kwargs`, see [`PosteriorStats.hdi`](@extref).
 """
 function PosteriorStats.hdi(data::InferenceObjects.InferenceData; kwargs...)
     return PosteriorStats.hdi(data.posterior; kwargs...)
diff --git a/ext/InferenceObjectsPosteriorStatsExt/loo.jl b/ext/InferenceObjectsPosteriorStatsExt/loo.jl
@@ -6,6 +6,8 @@ Compute PSIS-LOO from log-likelihood values in `data`.
 
 If more than one log-likelihood variable is present, then `var_name` must be provided.
 
+For more details and a description of the `kwargs`, see [`PosteriorStats.loo`](@extref).
+
 # Examples
 
 Calculate PSIS-LOO of a model:
diff --git a/ext/InferenceObjectsPosteriorStatsExt/loo_pit.jl b/ext/InferenceObjectsPosteriorStatsExt/loo_pit.jl
@@ -9,7 +9,10 @@ Compute LOO-PIT values using existing normalized log LOO importance weights.
     the only observed data variable is used.
   - `y_pred_name`: Name of posterior predictive variable in `idata.posterior_predictive`.
     If not provided, then `y_name` is used.
-  - `kwargs`: Remaining keywords are forwarded to the base method of `loo_pit`.
+  - `kwargs`: Remaining keywords are forwarded to the base method
+    [`PosteriorStats.loo_pit`](@extref).
+
+See [`PosteriorStats.loo_pit`](@extref) for more details.
 
 # Examples
 
@@ -23,9 +26,9 @@ julia> idata = load_example_data("centered_eight");
 julia> loo_result = loo(idata; var_name=:obs);
 
 julia> loo_pit(idata, loo_result.psis_result.log_weights; y_name=:obs)
-╭───────────────────────────────────────────╮
-│ 8-element DimArray{Float64,1} loo_pit_obs │
-├───────────────────────────────────────────┴──────────────────────────── dims ┐
+╭────────────────────────────────────────────╮
+│ 8-element DimArray{Float64, 1} loo_pit_obs │
+├────────────────────────────────────────────┴─────────────────────────── dims ┐
   ↓ school Categorical{String} [Choate, Deerfield, …, St. Paul's, Mt. Hermon] Unordered
 └──────────────────────────────────────────────────────────────────────────────┘
  "Choate"            0.943511
@@ -69,7 +72,9 @@ Compute LOO-PIT from groups in `idata` using PSIS-LOO.
     _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
     `ess`.
-  - `kwargs`: Remaining keywords are forwarded to the base method of `loo_pit`.
+  - `kwargs`: Remaining keywords are forwarded to [`PosteriorStats.loo_pit`](@extref).
+
+See [`PosteriorStats.loo_pit`](@extref) for more details.
 
 # Examples
 
@@ -81,9 +86,9 @@ julia> using ArviZExampleData, PosteriorStats
 julia> idata = load_example_data("centered_eight");
 
 julia> loo_pit(idata; y_name=:obs)
-╭───────────────────────────────────────────╮
-│ 8-element DimArray{Float64,1} loo_pit_obs │
-├───────────────────────────────────────────┴──────────────────────────── dims ┐
+╭────────────────────────────────────────────╮
+│ 8-element DimArray{Float64, 1} loo_pit_obs │
+├────────────────────────────────────────────┴─────────────────────────── dims ┐
   ↓ school Categorical{String} [Choate, Deerfield, …, St. Paul's, Mt. Hermon] Unordered
 └──────────────────────────────────────────────────────────────────────────────┘
  "Choate"            0.943511
diff --git a/ext/InferenceObjectsPosteriorStatsExt/r2_score.jl b/ext/InferenceObjectsPosteriorStatsExt/r2_score.jl
@@ -10,6 +10,8 @@ Compute ``R²`` from `idata`, automatically formatting the predictions to the co
   - `y_pred_name`: Name of posterior predictive variable in `idata.posterior_predictive`.
     If not provided, then `y_name` is used.
 
+See [`PosteriorStats.r2_score`](@extref) for more details.
+
 # Examples
 
 ```jldoctest
diff --git a/ext/InferenceObjectsPosteriorStatsExt/summarize.jl b/ext/InferenceObjectsPosteriorStatsExt/summarize.jl
@@ -2,7 +2,8 @@
     summarystats(data::InferenceData; group=:posterior, kwargs...) -> SummaryStats
     summarystats(data::Dataset; kwargs...) -> SummaryStats
 
-Compute default summary statistics for the data using `summarize`.
+Compute default summary statistics for the data using
+[`PosteriorStats.summarize`](@ref PosteriorStats.summarize(::InferenceData)).
 """
 function StatsBase.summarystats(data::InferenceObjects.InferenceData; kwargs...)
     return PosteriorStats.summarize(data; kwargs...)
@@ -18,7 +19,7 @@ end
 Compute summary statistics for the data using the provided functions.
 
 For verbose variable labels, provide `compat_labels=false`. For details on `stats_funs` and
-`kwargs`, see the main `summarize` method.
+`kwargs`, see [`PosteriorStats.summarize`](@extref).
 
 # Examples
 
diff --git a/ext/InferenceObjectsPosteriorStatsExt/waic.jl b/ext/InferenceObjectsPosteriorStatsExt/waic.jl
@@ -6,6 +6,8 @@ Compute WAIC from log-likelihood values in `data`.
 
 If more than one log-likelihood variable is present, then `var_name` must be provided.
 
+See [`PosteriorStats.waic`](@extref) for more details.
+
 # Examples
 
 Calculate WAIC of a model:
diff --git a/src/convert_dataset.jl b/src/convert_dataset.jl
@@ -4,7 +4,7 @@ Base.convert(::Type{Dataset}, obj::Dataset) = obj
 """
     convert_to_dataset(obj; group = :posterior, kwargs...) -> Dataset
 
-Convert a supported object to a `Dataset`.
+Convert a supported object to a [`Dataset`](@ref).
 
 In most cases, this function calls [`convert_to_inference_data`](@ref) and returns the
 corresponding `group`.
diff --git a/src/convert_inference_data.jl b/src/convert_inference_data.jl
@@ -1,7 +1,7 @@
 """
     convert(::Type{InferenceData}, obj)
 
-Convert `obj` to an `InferenceData`.
+Convert `obj` to an [`InferenceData`](@ref).
 
 `obj` can be any type for which [`convert_to_inference_data`](@ref) is defined.
 """
@@ -23,7 +23,7 @@ See [`convert_to_dataset`](@ref)
 # Arguments
 
   - `obj` can be many objects. Basic supported types are:
-    
+
       + [`InferenceData`](@ref): return unchanged
       + [`Dataset`](@ref)/`DimensionalData.AbstractDimStack`: add to `InferenceData` as the only
         group
@@ -40,7 +40,7 @@ More specific types may be documented separately.
 
   - `dims`: a collection mapping variable names to collections of objects containing
     dimension names. Acceptable such objects are:
-    
+
       + `Symbol`: dimension name
       + `Type{<:DimensionsionalData.Dimension}`: dimension type
       + `DimensionsionalData.Dimension`: dimension, potentially with indices
diff --git a/src/dataset.jl b/src/dataset.jl
diff --git a/src/from_dict.jl b/src/from_dict.jl
diff --git a/src/from_namedtuple.jl b/src/from_namedtuple.jl
diff --git a/src/inference_data.jl b/src/inference_data.jl
diff --git a/src/io.jl b/src/io.jl
