Fix docs CI pipeline for GeneralisedFilters

.buildkite/pipeline.yml

@@ -0,0 +1,50 @@
+steps:
+  - label: ":julia: Test SSMProblems on Julia v{{matrix.version}}"
+    matrix:
+      setup:
+        version:
+          - "1"
+    plugins:
+      - JuliaCI/julia#v1:
+          version: "{{matrix.version}}"
+    commands:
+      - cd SSMProblems
+      - |
+        julia --project -e '
+          import Pkg
+          println("+++ :julia: Running SSMProblems tests")
+          Pkg.instantiate()
+          Pkg.test(coverage=false)'
+    agents:
+      queue: "juliagpu"
+    timeout_in_minutes: 60
+    # Don't run Buildkite if the commit message includes the text [skip tests]
+    if: build.message !~ /\[skip tests\]/
+
+  - label: ":julia: :nvidia: Test GeneralisedFilters on Julia v{{matrix.version}}"
+    matrix:
+      setup:
+        version:
+          - "1"
+    env:
+      GROUP: CUDA
+      JULIA_CUDA_USE_BINARYBUILDER: "false"
+    plugins:
+      - JuliaCI/julia#v1:
+          version: "{{matrix.version}}"
+    commands:
+      - cd GeneralisedFilters
+      - |
+        julia --project -e '
+          import Pkg
+          println("+++ :julia: Dev-ing SSMProblems")
+          Pkg.develop(path="../SSMProblems")
+          println("+++ :julia: Running GeneralisedFilters tests")
+          Pkg.instantiate()
+          Pkg.test(coverage=false)'
+    agents:
+      queue: "juliagpu"
+      cuda: "*"
+    timeout_in_minutes: 120
+    # Don't run Buildkite if the commit message includes the text [skip tests]
+    if: build.message !~ /\[skip tests\]/

.github/workflows/Documentation.yml

@@ -25,8 +25,10 @@ jobs:
         pkg:
           - name: GeneralisedFilters
             dir: './GeneralisedFilters'
+            additional_paths: "./SSMProblems"
           - name: SSMProblems
             dir: './SSMProblems'
+            additional_paths: ""
 
     steps:
       - uses: actions/checkout@v4
@@ -35,7 +37,8 @@ jobs:
           version: '1'
       - uses: julia-actions/cache@v1
       - name: Install dependencies
-        run: julia --project=${{ matrix.pkg.dir }}/docs/ --color=yes -e '
+        run: |
+          julia --project=${{ matrix.pkg.dir }}/docs/ --color=yes -e '
           using Pkg;
           Pkg.Registry.update();
           Pkg.develop(PackageSpec(path="${{ matrix.pkg.dir }}"));
@@ -47,6 +50,7 @@ jobs:
         uses: TuringLang/actions/DocsDocumenter@main
         with:
           pkg_path: ${{ matrix.pkg.dir }}
+          additional_pkg_paths: ${{ matrix.pkg.additional_paths }}
           doc-path: ${{ matrix.pkg.dir }}/docs
           doc-make-path: ${{ matrix.pkg.dir }}/docs/make.jl
           doc-build-path: ${{ matrix.pkg.dir }}/docs/build

GeneralisedFilters/docs/Project.toml

@@ -0,0 +1,3 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"

GeneralisedFilters/docs/literate.jl

@@ -0,0 +1,19 @@
+# Retrieve name of example and output directory
+if length(ARGS) != 2
+    error("please specify the name of the example and the output directory")
+end
+const EXAMPLE = ARGS[1]
+const OUTDIR = ARGS[2]
+
+# Activate environment
+# Note that each example's Project.toml must include Literate as a dependency
+using Pkg: Pkg
+const EXAMPLEPATH = joinpath(@__DIR__, "..", "examples", EXAMPLE)
+Pkg.activate(EXAMPLEPATH)
+# Pkg.develop(joinpath(@__DIR__, "..", "..", "SSMProblems"))
+Pkg.instantiate()
+using Literate: Literate
+
+# Convert to markdown and notebook
+const SCRIPTJL = joinpath(EXAMPLEPATH, "script.jl")
+Literate.markdown(SCRIPTJL, OUTDIR; name=EXAMPLE, execute=true)

GeneralisedFilters/docs/make.jl

@@ -0,0 +1,76 @@
+push!(LOAD_PATH, "../src/")
+
+#
+# With minor changes from https://github.com/JuliaGaussianProcesses/AbstractGPs.jl/docs
+#
+### Process examples
+# Always rerun examples
+const EXAMPLES_OUT = joinpath(@__DIR__, "src", "examples")
+ispath(EXAMPLES_OUT) && rm(EXAMPLES_OUT; recursive=true)
+mkpath(EXAMPLES_OUT)
+
+# Install and precompile all packages
+# Workaround for https://github.com/JuliaLang/Pkg.jl/issues/2219
+examples = filter!(isdir, readdir(joinpath(@__DIR__, "..", "examples"); join=true))
+above = joinpath(@__DIR__, "..")
+ssmproblems_path = joinpath(above, "..", "SSMProblems")
+let script = "using Pkg; Pkg.activate(ARGS[1]); Pkg.develop(path=\"$(above)\"); Pkg.develop(path=\"$(ssmproblems_path)\"); Pkg.instantiate()"
+    for example in examples
+        if !success(`$(Base.julia_cmd()) -e $script $example`)
+            error(
+                "project environment of example ",
+                basename(example),
+                " could not be instantiated",
+            )
+        end
+    end
+end
+# Run examples asynchronously
+processes = let literatejl = joinpath(@__DIR__, "literate.jl")
+    map(examples) do example
+        return run(
+            pipeline(
+                `$(Base.julia_cmd()) $literatejl $(basename(example)) $EXAMPLES_OUT`;
+                stdin=devnull,
+                stdout=devnull,
+                stderr=stderr,
+            );
+            wait=false,
+        )::Base.Process
+    end
+end
+
+# Check that all examples were run successfully
+isempty(processes) || success(processes) || error("some examples were not run successfully")
+
+# Building Documenter
+using Documenter
+using GeneralisedFilters
+
+DocMeta.setdocmeta!(
+    GeneralisedFilters, :DocTestSetup, :(using GeneralisedFilters); recursive=true
+)
+
+makedocs(;
+    sitename="GeneralisedFilters",
+    format=Documenter.HTML(; size_threshold=1000 * 2^11), # 1Mb per page
+    pages=[
+        "Home" => "index.md",
+        "Examples" => [
+            map(
+                (x) -> joinpath("examples", x),
+                filter!(filename -> endswith(filename, ".md"), readdir(EXAMPLES_OUT)),
+            )...,
+        ],
+    ],
+    #strict=true,
+    checkdocs=:exports,
+    doctestfilters=[
+        # Older versions will show "0 element Array" instead of "Type[]".
+        r"(Any\[\]|0-element Array{.+,[0-9]+})",
+        # Older versions will show "Array{...,1}" instead of "Vector{...}".
+        r"(Array{.+,\s?1}|Vector{.+})",
+        # Older versions will show "Array{...,2}" instead of "Matrix{...}".
+        r"(Array{.+,\s?2}|Matrix{.+})",
+    ],
+)

GeneralisedFilters/docs/src/index.md

@@ -0,0 +1,25 @@
+# GeneralisedFilters
+
+## Installation
+
+In the `julia` REPL:
+
+```julia
+] add GeneralisedFilters
+```
+
+## Documentation
+
+`GeneralisedFilters` provides implementations of various filtering and
+smoothing algorithms for state-space models (SSMs). The goal of the package is
+to provide a modular and extensible framework for implementing advanced
+algorithms including Rao-Blackwellised particle filters, two-filter smoothers,
+and particle Gibbs/conditional SMC. Performance is a primary focus of this work,
+with type stability, GPU-acceleration, and efficient history storage being key
+design goals.
+
+### Interface
+```@autodocs
+Modules = [GeneralisedFilters]
+Order   = [:type, :function, :module]
+```

GeneralisedFilters/examples/demo-example/Project.toml

@@ -0,0 +1,4 @@
+[deps]
+GeneralisedFilters = "3ef92589-7ab8-43f9-b5b9-a3a0c86ecbb7"
+Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
+SSMProblems = "26aad666-b158-4e64-9d35-0e672562fa48"

GeneralisedFilters/examples/demo-example/script.jl

@@ -0,0 +1,6 @@
+# # Demo Example
+#
+# An empty example to check that the docs build correctly
+
+using SSMProblems
+using GeneralisedFilters