Examples in the docs: base PR for cleaning up notebook workflow

docs/Project.toml

@@ -1,6 +1,12 @@
 [deps]
+Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Flux = "587475ba-b771-5e3f-ad9e-33799f191a9c"
+KernelFunctions = "ec8451be-7e33-11e9-00cf-bbf324bd1392"
+Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
+MLDataUtils = "cc2ba9b6-d476-5e6d-8eaf-a92d5412d41d"
 PDMats = "90014a1f-27ba-587c-ab20-58faa44d9150"
+Zygote = "e88e6eb3-aa80-5325-afca-941959d7151f"
 
 [compat]
 Documenter = "0.27"

docs/README.md

@@ -0,0 +1,35 @@
+# How to build the docs locally
+
+Assuming you are in this (docs/) directory:
+
+Install docs dependencies:
+```bash
+julia --project=. -e 'using Pkg; Pkg.instantiate()'
+```
+This will use the last released KernelFunctions.jl for building the docs. 
+
+If instead you want to reflect the local state of the Git repository in your built docs, make sure to change the dependency to the development version:
+```bash
+julia --project=. -e "using Pkg; Pkg.develop(path=\"$(readlink -f ..)\")"
+```
+To undo the pinning to the local path by the previous command, run
+```bash
+julia --project=. -e 'using Pkg; Pkg.free("KernelFunctions")'
+```
+
+To actually build the docs, run
+```bash
+julia --project=. make.jl
+```
+The built docs will be underneath build/
+
+# How to contribute to the docs
+
+## To add additional docs dependencies
+
+```bash
+julia --project=. -e 'using Pkg; Pkg.add("NewDependency")'
+```
+and commit the changes to Project.toml
+
+

docs/make.jl

@@ -1,4 +1,5 @@
 using Documenter
+using Literate
 
 # Print `@debug` statements (https://github.com/JuliaDocs/Documenter.jl/issues/955)
 if haskey(ENV, "GITHUB_ACTIONS")
@@ -7,6 +8,21 @@ end
 
 using KernelFunctions
 
+const EXAMPLES_SRC = joinpath(@__DIR__, "..", "examples")
+const EXAMPLES_OUT = joinpath(@__DIR__, "src", "examples")
+const BLACKLIST = ["deepkernellearning", "kernelridgeregression", "svm"]
+
+if ispath(EXAMPLES_OUT)
+    rm(EXAMPLES_OUT; recursive=true)
+end
+
+for filepath in readdir(EXAMPLES_SRC; join=true)
+    endswith(filepath, ".jl") || continue
+    any([occursin(blacklistname, filepath) for blacklistname in BLACKLIST]) && continue
+    Literate.markdown(filepath, EXAMPLES_OUT; documenter=true)
+    Literate.notebook(filepath, EXAMPLES_OUT; documenter=true)
+end
+
 DocMeta.setdocmeta!(
     KernelFunctions,
     :DocTestSetup,
@@ -20,9 +36,9 @@ DocMeta.setdocmeta!(
 )
 
 makedocs(;
-    sitename="KernelFunctions",
-    format=Documenter.HTML(),
     modules=[KernelFunctions],
+    sitename="KernelFunctions.jl",
+    format=Documenter.HTML(),
     pages=[
         "Home" => "index.md",
         "userguide.md",
@@ -32,8 +48,10 @@ makedocs(;
         "theory.md",
         "create_kernel.md",
         "API" => "api.md",
-        "Examples" => "example.md",
-        "Design" => "design.md",
+        # "Examples" =>
+        #     joinpath.(
+        #         "examples", filter(filename -> endswith(filename, ".md"), readdir(EXAMPLES_OUT))
+        #     ),
     ],
     strict=true,
     checkdocs=:exports,

examples/svm.jl

@@ -20,7 +20,7 @@ function f(x, k, λ)
            inv(kernelmatrix(k, X; obsdim=1) + exp(λ[1]) * I) *
            y
 end # Optimal prediction f
-svmloss(y, ŷ) = ŷ -> sum(maximum.(0.0, 1 - y * ŷ)) - λ * norm(ŷ)(f(X, k, λ)) # Total svm loss with regularisation
-pred = f(Xgrid, k, λ) #Compute prediction on a grid
+svmloss(y, ŷ, λ) = ŷ -> sum(maximum.(0.0, 1 - y * ŷ)) - λ * norm(ŷ)(f(X, k, λ)) # Total svm loss with regularisation
+pred = f(Xgrid, k, 0.1) #Compute prediction on a grid
 contourf(xgrid, xgrid, pred)
 scatter!(eachcol(X)...; color=y, lab="data")