Merge pull request #3 from JuliaGaussianProcesses/docs

Add documentation

.github/workflows/docs.yml

@@ -0,0 +1,34 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - master
+    tags: '*'
+  pull_request:
+
+concurrency:
+  # Skip intermediate builds: always.
+  # Cancel intermediate builds: only if it is a pull request build.
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - 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()'
+        env:
+          JULIA_PKG_SERVER: ''
+      - name: Build and deploy
+        env:
+          GKSwstype: nul # turn off GR's interactive plotting for notebooks
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # For authentication with SSH deploy key
+          JULIA_DEBUG: Documenter # Print `@debug` statements (https://github.com/JuliaDocs/Documenter.jl/issues/955)
+        run: julia --project=docs/ docs/make.jl

README.md

@@ -1,11 +1,16 @@
 # EasyGPs
 
+[![Docs: stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://JuliaGaussianProcesses.github.io/EasyGPs.jl/stable)
+[![Docs: dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://JuliaGaussianProcesses.github.io/EasyGPs.jl/dev)
 [![CI](https://github.com/JuliaGaussianProcesses/EasyGPs.jl/actions/workflows/CI.yml/badge.svg)](https://github.com/JuliaGaussianProcesses/EasyGPs.jl/actions/workflows/CI.yml)
 [![Codecov](https://codecov.io/gh/JuliaGaussianProcesses/EasyGPs.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/JuliaGaussianProcesses/EasyGPs.jl)
 
-EasyGPs is a front-end package for the JuliaGP ecosystem. It is geared towards making it
-very easy to train GP models with a high-level API that does not require in-depth knowledge
-of the low-level algorithmic choices.
+EasyGPs.jl is a package that defines a high-level API for the JuliaGaussianProcesses eco-
+system. It is aimed at people who want to use GPs to do exploratory analysis, model data and
+make predictions without having to deal with all the low-level detail.
+
+> [!NOTE]  
+> This is currently an experimental package and may undergo rapid breaking changes.
 
 ## Usage
 

docs/Project.toml

@@ -0,0 +1,6 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+EasyGPs = "dcfb08e9-329b-4987-96a2-39b8bd2240d0"
+
+[compat]
+Documenter = "1"

docs/make.jl

@@ -0,0 +1,41 @@
+### Process examples
+using Pkg
+Pkg.add(Pkg.PackageSpec(; url="https://github.com/JuliaGaussianProcesses/JuliaGPsDocs.jl")) # While the package is unregistered, it's a workaround
+
+using JuliaGPsDocs
+
+using EasyGPs
+
+JuliaGPsDocs.generate_examples(EasyGPs)
+
+### Build documentation
+using Documenter
+
+# Doctest setup
+DocMeta.setdocmeta!(
+    EasyGPs,
+    :DocTestSetup,
+    quote
+        using EasyGPs
+    end;  # we have to load all packages used (implicitly) within jldoctest blocks in the API docstrings
+    recursive=true,
+)
+
+makedocs(;
+    sitename="EasyGPs.jl",
+    format=Documenter.HTML(;
+        size_threshold_ignore=[
+            "examples/0-mauna-loa/index.md",
+        ],
+    ),
+    modules=[EasyGPs],
+    pages=[
+        "Home" => "index.md",
+        "Examples" => JuliaGPsDocs.find_generated_examples(EasyGPs),
+    ],
+    warnonly=true,
+    checkdocs=:exports,
+    doctestfilters=JuliaGPsDocs.DOCTEST_FILTERS,
+)
+
+deploydocs(; repo="github.com/JuliaGaussianProcesses/EasyGPs.jl.git", push_preview=true)

docs/src/index.md

@@ -0,0 +1,27 @@
+# EasyGPs.jl
+
+EasyGPs.jl is a package that defines a high-level API for the JuliaGaussianProcesses eco-
+system. It is aimed at people who want to use GPs to do exploratory analysis, model data and
+make predictions without having to deal with all the low-level detail.
+
+!!! note
+    This is currently an experimental package and may undergo rapid changes.
+
+## Usage
+
+In order to fit a GP, define one according to the familiar AbstractGP.jl interface and
+let EasyGPs.jl handle the rest. The entry point for this is `EasyGPs.fit` (not exported):
+
+```julia
+using EasyGPs
+
+kernel = 1.0 * with_lengthscale(SEKernel(), 1.0)
+gp = with_gaussian_noise(GP(0.0, kernel), 0.1)
+x = 0:0.1:10
+y = sin.(x) .+ 0.1 .* randn(length(x))
+fitted_gp = EasyGPs.fit(gp, x, y)
+```
+
+Under the hood, this will recognize the parameters (mean, variance, lengthscale) of the `GP`
+you defined and automatically construct a parameterized model. It will then choose a cost
+function, optimizer, and AD backend, and determine the optimal parameters.