Merge pull request #6 from SciML/docs

Build a proper documentation

.github/workflows/Documentation.yml

@@ -0,0 +1,32 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - main
+      - 'release-'
+    tags: '*'
+  pull_request:
+  schedule:
+    - cron: '34 21 * * 4'
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@latest
+        with:
+          version: '1'
+      - name: Install dependencies
+        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+      - name: Build and deploy
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # For authentication with SSH deploy key
+        run: julia --project=docs/ --code-coverage=user docs/make.jl
+      - uses: julia-actions/julia-processcoverage@v1
+        with:
+          directories: src
+      - uses: codecov/codecov-action@v3
+        with:
+          files: lcov.info

README.md

@@ -1,5 +1,14 @@
 # SurrogatesBase.jl
 
+[![Join the chat at https://julialang.zulipchat.com #sciml-bridged](https://img.shields.io/static/v1?label=Zulip&message=chat&color=9558b2&labelColor=389826)](https://julialang.zulipchat.com/#narrow/stream/279055-sciml-bridged)
+[![Global Docs](https://img.shields.io/badge/docs-SciML-blue.svg)](https://docs.sciml.ai/SurrogatesBase/stable/)
+
+[![codecov](https://codecov.io/gh/SciML/SurrogatesBase.jl/branch/master/graph/badge.svg?token=FwXaKBNW67)](https://codecov.io/gh/SciML/SurrogatesBase.jl)
+[![Build Status](https://github.com/SciML/SurrogatesBase.jl/workflows/CI/badge.svg)](https://github.com/SciML/SurrogatesBase.jl/actions?query=workflow%3ACI)
+
+[![ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://img.shields.io/badge/ColPrac-Contributor%27s%20Guide-blueviolet)](https://github.com/SciML/ColPrac)
+[![SciML Code Style](https://img.shields.io/static/v1?label=code%20style&message=SciML&color=9558b2&labelColor=389826)](https://github.com/SciML/SciMLStyle)
+
 API for deterministic and stochastic surrogates.
 
 Given data $((x_1, y_1), \ldots, (x_N, y_N))$ obtained by evaluating a function $y_i =
@@ -10,132 +19,4 @@ uses the data to approximate $f$ or some statistic of $p_{Y|X}$ (e.g. the mean),
 whereas a **stochastic surrogate** is a stochastic process (e.g. a [Gaussian process
 approximation](https://en.wikipedia.org/wiki/Gaussian_process_approximations)) that uses
 the data to approximate $f$ or $p_{Y|X}$ *and* quantify the uncertainty of the
-approximation.
-
-## Deterministic Surrogates
-
-Deterministic surrogates `s` are subtypes of `SurrogatesBase.AbstractDeterministicSurrogate`, 
-which is a subtype of `Function`.
-
-### Required methods
-
-The method `update!(s, xs, ys)` **must** be implemented and the surrogate **must** be
-[callable](https://docs.julialang.org/en/v1/manual/methods/#Function-like-objects)
-`s(xs)`, where `xs` is a `Vector` of input points and `ys` is a `Vector` of corresponding evaluations.
-
-Calling `update!(s, xs, ys)` refits the surrogate `s` to include evaluations `ys` at points `xs`.
-The result of `s(xs)` is a `Vector` of evaluations of the surrogate at points `xs`, corresponding to approximations of the underlying function at points `xs` respectively.
-
-For single points `x` and `y`, call these methods via `update!(s, [x], [y])`
-and `s([x])`.
-
-### Optional methods
-
-If the surrogate `s` wants to expose current parameter values, the method `parameters(s)` **must** be implemented.
-
-If the surrogate `s` has tunable hyperparameters, the methods
-`update_hyperparameters!(s, prior)` and `hyperparameters(s)` **must** be implemented.
-
-Calling `update_hyperparameters!(s, prior)` updates the hyperparameters of the surrogate `s` by performing hyperparameter optimization using the information in `prior`. After the hyperparameters of `s` are updated, `s` is fit to past evaluations.
-Calling `hyperparameters(s)` returns current values of hyperparameters.
-
-### Example
-
-```julia
-using SurrogatesBase
-
-struct RBF{T} <: AbstractDeterministicSurrogate
-    scale::T
-    centers::Vector{T}
-    weights::Vector{T}
-end
-
-(rbf::RBF)(xs) = [rbf.weights' * exp.(-rbf.scale * (x .- rbf.centers).^2)
-                  for x in xs]
-
-function SurrogatesBase.update!(rbf::RBF, xs, ys)
-    # Refit the surrogate by updating rbf.weights to include new 
-    # evaluations ys at points xs
-    return rbf
-end
-
-SurrogatesBase.parameters(rbf::RBF) = rbf.centers, rbf.weights
-
-SurrogatesBase.hyperparameters(rbf::RBF) = rbf.scale
-
-function SurrogatesBase.update_hyperparameters!(rbf::RBF, prior)
-    # update rbf.scale and fit the surrogate by adapting rbf.weights
-    return rbf
-end
-```
-
-## Stochastic Surrogates
-
-Stochastic surrogates `s` are subtypes of `SurrogatesBase.AbstractStochasticSurrogate`.
-
-### Required methods
-
-The methods `update!(s, xs, ys)` and `finite_posterior(s, xs)` **must** be implemented, where `xs` is a `Vector` of input points and `ys` is a `Vector` of corresponding observed samples.
-
-Calling `update!(s, xs, ys)` refits the surrogate `s` to include observations `ys` at points `xs`.
-
-For single points `x` and `y`, call the `update!(s, xs, ys)` via `update!(s, [x], [y])`.
-
-Calling `finite_posterior(s, xs)` returns an object that provides methods for  working with the finite 
-dimensional posterior distribution at points `xs`.
-The following methods might be supported:
-
-- `mean(finite_posterior(s,xs))` returns a `Vector` of posterior means at `xs`
-- `var(finite_posterior(s,xs))` returns a `Vector` of posterior variances at `xs`
-- `mean_and_var(finite_posterior(s,xs))` returns a `Tuple` consisting of a `Vector`
-of posterior means and a `Vector` of posterior variances at `xs`
-- `rand(finite_posterior(s,xs))` returns a `Vector`, which is a sample from the joint posterior at points `xs`
-
-### Optional methods
-
-If the surrogate `s` wants to expose current parameter values, the method `parameters(s)` **must** be implemented.
-
-If the surrogate `s` has tunable hyper-parameters, the methods
-`update_hyperparameters!(s, prior)` and `hyperparameters(s)` **must** be implemented.
-
-Calling `update_hyperparameters!(s, prior)` updates the hyperparameters of the surrogate `s` by performing hyperparameter optimization using the information in `prior`. After the hyperparameters of `s` are updated, `s` is fit to past samples.
-Calling `hyperparameters(s)` returns current values of hyperparameters.
-
-
-### Example
-
-```julia
-using SurrogatesBase
-
-mutable struct GaussianProcessSurrogate{D, R, GP, H <: NamedTuple} <: AbstractStochasticSurrogate
-    xs::Vector{D}
-    ys::Vector{R}
-    gp_process::GP
-    hyperparameters::H
-end
-
-function SurrogatesBase.update!(g::GaussianProcessSurrogate, new_xs, new_ys)
-    append!(g.xs, new_xs)
-    append!(g.ys, new_ys)
-    # condition the prior `g.gp_process` on new data to obtain a posterior
-    # update g.gp_process to the posterior process
-    return g
-end
-
-function SurrogatesBase.finite_posterior(g::GaussianProcessSurrogate, xs)
-    # Return a finite dimensional projection of g.gp_process at points xs.
-    # The returned object GP_finite supports methods mean(GP_finite) and
-    # var(GP_finite) for obtaining the vector of means and variances at points xs.
-end
-
-SurrogatesBase.hyperparameters(g::GaussianProcessSurrogate) = g.hyperparameters
-
-function SurrogatesBase.update_hyperparameters!(g::GaussianProcessSurrogate, prior)
-    # Use prior on hyperparameters, e.g., parameters uniformly distributed 
-    # between an upper and lower bound, to perform hyperparameter optimization.
-    # Set g.hyperparameters to the improved hyperparameters.
-    # Fit a Gaussian process that uses the updated hyperparameters to past
-    # samples and save it in g.gp_process.
-    return g
-end
-```
+approximation.

docs/.gitignore

@@ -0,0 +1,2 @@
+build/
+site/

docs/Project.toml

@@ -0,0 +1,6 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+SurrogatesBase = "89f642e6-4179-4274-8202-c11f4bd9a72c"
+
+[compat]
+Documenter = "1"

docs/make.jl

@@ -0,0 +1,23 @@
+using Documenter, SurrogatesBase
+
+cp("./docs/Manifest.toml", "./docs/src/assets/Manifest.toml", force = true)
+cp("./docs/Project.toml", "./docs/src/assets/Project.toml", force = true)
+
+pages = [
+    "Home" => "index.md",
+    "interface.md",
+    "api.md"
+]
+
+ENV["GKSwstype"] = "100"
+
+makedocs(modules = [SurrogatesBase],
+    sitename = "SurrogatesBase.jl",
+    clean = true,
+    doctest = false,
+    linkcheck = true,
+    format = Documenter.HTML(assets = ["assets/favicon.ico"],
+        canonical = "https://docs.sciml.ai/SurrogatesBase/stable/"),
+    pages = pages)
+
+deploydocs(repo = "github.com/SciML/SurrogatesBase.jl"; push_preview = true)

docs/src/api.md

@@ -0,0 +1,5 @@
+# API
+
+```@autodocs
+Modules = [SurrogatesBase]
+```

docs/src/index.md

@@ -0,0 +1,96 @@
+# SurrogatesBase.jl: A Common Interface for Surrogate Libraries
+
+API for deterministic and stochastic surrogates.
+
+Given data $((x_1, y_1), \ldots, (x_N, y_N))$ obtained by evaluating a function $y_i =
+f(x_i)$ or sampling from a conditional probability density $p_{Y|X}(Y = y_i|X = x_i)$,
+a **deterministic surrogate** is a function $s(x)$ (e.g. a [radial basis function
+interpolator](https://en.wikipedia.org/wiki/Radial_basis_function_interpolation)) that
+uses the data to approximate $f$ or some statistic of $p_{Y|X}$ (e.g. the mean),
+whereas a **stochastic surrogate** is a stochastic process (e.g. a [Gaussian process
+approximation](https://en.wikipedia.org/wiki/Gaussian_process_approximations)) that uses
+the data to approximate $f$ or $p_{Y|X}$ *and* quantify the uncertainty of the
+approximation.
+
+## Installation
+
+To install SurrogatesBase.jl, use the Julia package manager:
+
+```julia
+using Pkg
+Pkg.add("SurrogatesBase")
+```
+
+## Contributing
+
+  - Please refer to the
+    [SciML ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://github.com/SciML/ColPrac/blob/master/README.md)
+    for guidance on PRs, issues, and other matters relating to contributing to SciML.
+
+  - See the [SciML Style Guide](https://github.com/SciML/SciMLStyle) for common coding practices and other style decisions.
+  - There are a few community forums:
+
+      + The #diffeq-bridged and #sciml-bridged channels in the
+        [Julia Slack](https://julialang.org/slack/)
+      + The #diffeq-bridged and #sciml-bridged channels in the
+        [Julia Zulip](https://julialang.zulipchat.com/#narrow/stream/279055-sciml-bridged)
+      + On the [Julia Discourse forums](https://discourse.julialang.org)
+      + See also [SciML Community page](https://sciml.ai/community/)
+
+## Reproducibility
+
+```@raw html
+<details><summary>The documentation of this SciML package was built using these direct dependencies,</summary>
+```
+
+```@example
+using Pkg # hide
+Pkg.status() # hide
+```
+
+```@raw html
+</details>
+```
+
+```@raw html
+<details><summary>and using this machine and Julia version.</summary>
+```
+
+```@example
+using InteractiveUtils # hide
+versioninfo() # hide
+```
+
+```@raw html
+</details>
+```
+
+```@raw html
+<details><summary>A more complete overview of all dependencies and their versions is also provided.</summary>
+```
+
+```@example
+using Pkg # hide
+Pkg.status(; mode = PKGMODE_MANIFEST) # hide
+```
+
+```@raw html
+</details>
+```
+
+```@eval
+using TOML
+using Markdown
+version = TOML.parse(read("../../Project.toml", String))["version"]
+name = TOML.parse(read("../../Project.toml", String))["name"]
+link_manifest = "https://github.com/SciML/" * name * ".jl/tree/gh-pages/v" * version *
+                "/assets/Manifest.toml"
+link_project = "https://github.com/SciML/" * name * ".jl/tree/gh-pages/v" * version *
+               "/assets/Project.toml"
+Markdown.parse("""You can also download the
+[manifest]($link_manifest)
+file and the
+[project]($link_project)
+file.
+""")
+```