Fix and clean up documentation build by using @extref

.github/workflows/ci.yml

@@ -29,7 +29,7 @@ jobs:
           access_token: ${{ github.token }}
 
       # Do tests
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v5
       - uses: julia-actions/setup-julia@v1
         with:
           version: ${{ matrix.version }}

Project.toml

@@ -49,4 +49,4 @@ StaticArrays = "^1"
 Statistics = "1"
 StatsBase = "^0.34"
 TimeseriesSurrogates = "2.7"
-julia = "^1.10.6"
+julia = "^1.10.10"

docs/Project.toml

@@ -25,5 +25,6 @@ Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 TimeseriesSurrogates = "c804724b-8c18-5caa-8579-6025a0767c70"
 
 [compat]
+ComplexityMeasures = "^3.8"
 DynamicalSystemsBase = "3"
-julia = "^1.10.6"
+julia = "^1.10.10"

docs/build_docs_with_style.jl

@@ -1,40 +1,40 @@
 CI = get(ENV, "CI", nothing) == "true" || get(ENV, "GITHUB_TOKEN", nothing) !== nothing
 
- import Pkg
- Pkg.pkg"add Documenter@1"
+import Pkg
+Pkg.pkg"add Documenter@1"
 
- # Load documenter
- using Documenter
- using DocumenterTools: Themes
- ENV["JULIA_DEBUG"] = "Documenter"
+# Load documenter
+using Documenter
+using DocumenterTools: Themes
+ENV["JULIA_DEBUG"] = "Documenter"
 
- # For easier debugging when downloading from a specific branch.
- github_user = "JuliaDynamics"
- branch = "master"
- download_path = "https://raw.githubusercontent.com/$github_user/doctheme/$branch"
+# For easier debugging when downloading from a specific branch.
+github_user = "JuliaDynamics"
+branch = "master"
+download_path = "https://raw.githubusercontent.com/$github_user/doctheme/$branch"
 
- import Downloads
- for file in ("juliadynamics-lightdefs.scss", "juliadynamics-darkdefs.scss", "juliadynamics-style.scss")
-     Downloads.download("$download_path/$file", joinpath(@__DIR__, file))
- end
+import Downloads
+for file in ("juliadynamics-lightdefs.scss", "juliadynamics-darkdefs.scss", "juliadynamics-style.scss")
+    Downloads.download("$download_path/$file", joinpath(@__DIR__, file))
+end
 
- # create the themes
- for w in ("light", "dark")
-     header = read(joinpath(@__DIR__, "juliadynamics-style.scss"), String)
-     theme = read(joinpath(@__DIR__, "juliadynamics-$(w)defs.scss"), String)
-     write(joinpath(@__DIR__, "juliadynamics-$(w).scss"), header*"\n"*theme)
- end
+# create the themes
+for w in ("light", "dark")
+    header = read(joinpath(@__DIR__, "juliadynamics-style.scss"), String)
+    theme = read(joinpath(@__DIR__, "juliadynamics-$(w)defs.scss"), String)
+    write(joinpath(@__DIR__, "juliadynamics-$(w).scss"), header * "\n" * theme)
+end
 
- # compile the themes
- Themes.compile(joinpath(@__DIR__, "juliadynamics-light.scss"), joinpath(@__DIR__, "src/assets/themes/documenter-light.css"))
- Themes.compile(joinpath(@__DIR__, "juliadynamics-dark.scss"), joinpath(@__DIR__, "src/assets/themes/documenter-dark.css"))
+# compile the themes
+Themes.compile(joinpath(@__DIR__, "juliadynamics-light.scss"), joinpath(@__DIR__, "src/assets/themes/documenter-light.css"))
+Themes.compile(joinpath(@__DIR__, "juliadynamics-dark.scss"), joinpath(@__DIR__, "src/assets/themes/documenter-dark.css"))
 
- # Download and apply CairoMakie plotting style
- using CairoMakie
- Downloads.download("$download_path/style.jl", joinpath(@__DIR__, "style.jl"))
- include("style.jl")
+# Download and apply CairoMakie plotting style
+using CairoMakie
+Downloads.download("$download_path/style.jl", joinpath(@__DIR__, "style.jl"))
+include("style.jl")
 
- using DocumenterInterLinks
+using DocumenterInterLinks
 
 links = InterLinks(
     "ComplexityMeasures" => (
@@ -49,46 +49,48 @@ links = InterLinks(
     ),
 );
 
- function build_docs_with_style(pages, modules...; bib = nothing, authors = "George Datseris", draft = false, kwargs...)
-     settings = (
-         modules = [modules...],
-         format = Documenter.HTML(
-             prettyurls = CI,
-             assets = [
-                 asset("https://fonts.googleapis.com/css?family=Montserrat|Source+Code+Pro&display=swap", class=:css),
-             ],
-             collapselevel = 3,
-             size_threshold = 1250 * 2^10, 
-             size_threshold_warn = 750 * 2^10,
-             example_size_threshold = 100 * 2^10,
-             size_threshold_ignore = [
-                "examples/examples_associations.md", 
+function build_docs_with_style(pages, modules...; bib=nothing,
+    authors="Kristian Haaga, George Datseris and others", draft=false, kwargs...)
+    settings = (
+        modules=[modules...],
+        format=Documenter.HTML(
+            prettyurls=CI,
+            assets=[
+                asset("https://fonts.googleapis.com/css?family=Montserrat|Source+Code+Pro&display=swap", class=:css),
+            ],
+            collapselevel=3,
+            size_threshold=1250 * 2^10,
+            size_threshold_warn=750 * 2^10,
+            example_size_threshold=100 * 2^10,
+            size_threshold_ignore=[
+                "examples/examples_associations.md",
                 "examples/examples_independence.md",
                 "examples/examples_infer_graphs.md",
-             ]
-         ),
-         sitename = "$(modules[1]).jl",
-         authors,
-         pages,
-         draft,
-         doctest = false,
-         warnonly = false,
-         checkdocs = :exported,
-         kwargs...
-     )
+            ]
+        ),
+        sitename="$(modules[1]).jl",
+        authors,
+        pages,
+        draft,
+        doctest=false,
+        checkdocs=:exported,
+        # The following Documenter fails will NOT ERROR the docbuild!
+        warnonly=[:doctest, :missing_docs],
+        kwargs...
+    )
 
-     if isnothing(bib)
-         makedocs(; settings...)
-     else
-         makedocs(; plugins=[bib, links], settings...)
-     end
+    if isnothing(bib)
+        makedocs(; plugins=[links], settings...)
+    else
+        makedocs(; plugins=[links, bib], settings...)
+    end
 
-     if CI
-         deploydocs(
-             repo = "github.com/JuliaDynamics/$(modules[1]).jl.git",
-             target = "build",
-             push_preview = true
-         )
-     end
+    if CI
+        deploydocs(
+            repo="github.com/JuliaDynamics/$(modules[1]).jl.git",
+            target="build",
+            push_preview=true
+        )
+    end
 
- end 
+end

docs/make.jl

@@ -25,7 +25,7 @@ pages = [
         "api/cross_map_api.md",
     ],
     "Examples" => [
-        "Associations" => "examples/examples_associations.md", 
+        "Associations" => "examples/examples_associations.md",
         "Independence testing" => "examples/examples_independence.md",
         "Causal graph inference" => "examples/examples_infer_graphs.md",
     ],
@@ -43,9 +43,9 @@ bibliography = CitationBibliography(
     style=:authoryear
 )
 
-build_docs_with_style(pages, Associations, ComplexityMeasures, StateSpaceSets;
-    expandfirst = ["index.md"],
-    bib = bibliography,
-    pages = pages,
-    authors = "Kristian Agasøster Haaga, David Diego, Tor Einar Møller, George Datseris",
+build_docs_with_style(pages, Associations;
+    expandfirst=["index.md"],
+    bib=bibliography,
+    pages=pages,
+    authors="Kristian Agasøster Haaga, David Diego, Tor Einar Møller, George Datseris",
 )

docs/src/api/counts_and_probabilities_api.md

@@ -1,20 +1,18 @@
 
 ```@meta
-CollapsedDocStrings = true
+CollapsedDocStrings = false
 ```
 
 # [Multivariate counts and probabilities API](@id counts_and_probabilities_api)
 
 For counting and probabilities, Associations.jl extends the single-variable machinery
-in ComplexityMeasures.jl to multiple variables.
+in ComplexityMeasures.jl to multiple variables. See the following types:
 
-```@docs
-Associations.Counts
-Associations.counts(::OutcomeSpace)
-```
+- [`Counts`](@extref ComplexityMeasures.Counts)
+- [`Probabilities`](@extref ComplexityMeasures.Probabilities)
 
 ```@docs
-Associations.Probabilities
+Associations.counts(::OutcomeSpace)
 Associations.probabilities(::OutcomeSpace)
 ```
 
@@ -24,10 +22,10 @@ The utility function [`marginal`](@ref) is also useful.
 marginal
 ```
 
-## [Example: estimating [`Counts`](@ref) and [`Probabilities`](@ref)](@id tutorial_probabilities)
+## [Example: estimating [`Counts`](@extref ComplexityMeasures.Counts) and [`Probabilities`](@extref ComplexityMeasures.Probabilities)](@id tutorial_probabilities)
 
 Estimating multivariate counts (contingency matrices) and PMFs is simple. If the data are pre-discretized, then
-we can use [`UniqueElements`](@ref) to simply count the number of occurrences.
+we can use [`UniqueElements`](@extref ComplexityMeasures.UniqueElements) to simply count the number of occurrences.
 
 ```@example counts_probs_tutorial
 using Associations
@@ -47,7 +45,7 @@ probabilities(discretization, x, y, z)
 ```
 
 For numerical data, we can estimate both counts and probabilities using [`CodifyVariables`](@ref)
-with any count-based [`OutcomeSpace`](@ref).
+with any count-based [`OutcomeSpace`](@extref ComplexityMeasures.OutcomeSpace).
 
 ```@example counts_probs_tutorial
 using Associations
@@ -56,7 +54,7 @@ discretization = CodifyVariables(BubbleSortSwaps(m = 4))
 probabilities(discretization, x, y)
 ```
 
-For more fine-grained control, we can use [`CodifyPoints`](@ref) with one or several [`Encoding`](@ref)s.
+For more fine-grained control, we can use [`CodifyPoints`](@ref) with one or several [`Encoding`](@extref ComplexityMeasures.Encoding)s.
 
 ```@example counts_probs_tutorial
 using Associations

docs/src/api/cross_map_api.md

@@ -1,5 +1,5 @@
 ```@meta
-CollapsedDocStrings = true
+CollapsedDocStrings = false
 ```
 
 # Cross-map API