Examples in the docs: base PR for cleaning up notebook workflow (#303)

Following #314, this PR adds READMEs for how to build & add to the docs and examples, as well as tidying the workflow up a bit more. It makes all current examples run (with a warning to say they're under construction).

Author: st--

.gitignore

@@ -3,5 +3,4 @@
 /Manifest.toml
 /test/Manifest.toml
 coverage/
-src/update_v0.8.0
 .DS_store

docs/.gitignore

@@ -1,3 +1,3 @@
 build/
 site/
-src/examples/
+src/examples/

docs/Manifest.toml

@@ -1,5 +1,11 @@
 # This file is machine-generated - editing it directly is not advised
 
+[[AbstractFFTs]]
+deps = ["LinearAlgebra"]
+git-tree-sha1 = "051c95d6836228d120f5f4b984dd5aba1624f716"
+uuid = "621f4979-c628-5d54-868e-fcf4e3e8185c"
+version = "0.5.0"
+
 [[ArgTools]]
 uuid = "0dad84c5-d112-42e6-8d28-ef12dabb789f"
 
@@ -115,6 +121,12 @@ path = ".."
 uuid = "ec8451be-7e33-11e9-00cf-bbf324bd1392"
 version = "0.10.6"
 
+[[Kronecker]]
+deps = ["FillArrays", "LinearAlgebra", "NamedDims", "SparseArrays", "StatsBase"]
+git-tree-sha1 = "90e082a267982069e624ea0f825d324c86a01b4e"
+uuid = "2c470bb0-bcc8-11e8-3dad-c9649493f05e"
+version = "0.4.3"
+
 [[LibCURL]]
 deps = ["LibCURL_jll", "MozillaCACerts_jll"]
 uuid = "b27032c2-a3e7-50c8-80cd-2d36dbcbfd21"
@@ -173,6 +185,12 @@ uuid = "a63ad114-7e13-5084-954f-fe012c677804"
 [[MozillaCACerts_jll]]
 uuid = "14a3606d-f60d-562e-9121-12d972cd8159"
 
+[[NamedDims]]
+deps = ["AbstractFFTs", "LinearAlgebra", "Pkg", "Requires", "Statistics"]
+git-tree-sha1 = "e91d3ee8ac1514651b6e85686ca31257d17b1eb2"
+uuid = "356022a1-0364-5f58-8944-0da4b18d706f"
+version = "0.2.33"
+
 [[NetworkOptions]]
 uuid = "ca575930-c2e3-43a9-ace4-1e988b2c1908"
 

docs/Project.toml

@@ -1,10 +1,12 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 KernelFunctions = "ec8451be-7e33-11e9-00cf-bbf324bd1392"
+Kronecker = "2c470bb0-bcc8-11e8-3dad-c9649493f05e"
 PDMats = "90014a1f-27ba-587c-ab20-58faa44d9150"
 
 [compat]
 Documenter = "0.27"
 KernelFunctions = "0.10"
 PDMats = "0.11"
+Kronecker = "0.4"
 julia = "1.3"

docs/README.md

@@ -0,0 +1,63 @@
+# How to build the docs locally
+
+If you just want to modify or add an example, you can [build just the example](../examples/README.md) without having to build the full documentation locally.
+
+If you want to build the documentation, navigate to this (docs/) directory and open a Julia REPL.
+
+## Instantiation
+
+First activate the documentation environment:
+```julia
+julia> ] activate .
+```
+Alternatively, you can start Julia with `julia --project=.`.
+
+Then install all packages:
+```julia
+julia> ] instantiate
+```
+By default, this will use the development version of KernelFunctions in the parent directory.
+
+## Build
+
+To build the documentation, run (after activating the documentation environment)
+```julia
+julia> include("make.jl")
+```
+You can speed up the process if you do not execute the examples and comment out the
+relevant sections in `docs/make.jl`.
+
+The output is in the `docs/build/` directory and best viewed in a browser.
+The documentation uses pretty URLs which can be a hindrance if you browse the documentation locally.
+The [Documenter documentation](https://juliadocs.github.io/Documenter.jl/stable/man/guide/#Building-an-Empty-Document) suggests that
+
+> You can run a local web server out of the `docs/build` directory. One way to accomplish
+> this is to install the [LiveServer](https://github.com/tlienart/LiveServer.jl) Julia
+> package. You can then start the server with `julia -e 'using LiveServer; serve(dir="docs/build")'`.
+> Alternatively, if you have Python installed, you can start one with
+> `python3 -m http.server --bind localhost` (or `python -m SimpleHTTPServer` with Python 2).
+
+If you make any changes, you can run
+```julia
+julia> include("make.jl")
+```
+again to rebuild the documentation.
+
+# How to contribute to the docs
+
+## To add additional docs dependencies
+
+To add additional dependencies, run (after activating the documentation environment)
+```julia
+julia> ] add NewDependency
+```
+or, as a shell one-liner:
+```shell
+julia --project=. -e 'using Pkg; Pkg.add("NewDependency")'
+```
+and commit the changes to Project.toml and Manifest.toml.
+
+
+## To add examples
+
+See [../examples](../examples/README.md)

docs/literate.jl

@@ -8,6 +8,7 @@ const OUTDIR = ARGS[2]
 # Activate environment
 using Pkg: Pkg
 Pkg.activate(dirname(SCRIPTJL))
+# Note that each example's Project.toml must include Literate as a dependency
 Pkg.instantiate()
 using Literate: Literate
 
@@ -23,14 +24,13 @@ function preprocess(content)
 #
 #md # [![](https://img.shields.io/badge/show-nbviewer-579ACA.svg)](@__NBVIEWER_ROOT_URL__/examples/@__NAME__.ipynb)
 #md #
-# You are seeing the
+# *You are seeing the
 #md # HTML output generated by [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl) and
 #nb # notebook output generated by
 # [Literate.jl](https://github.com/fredrikekre/Literate.jl) from the
 # [Julia source file](@__REPO_ROOT_URL__/examples/@__NAME__/script.jl).
-# The corresponding
-#md # notebook can be viewed in [nbviewer](@__NBVIEWER_ROOT_URL__/examples/@__NAME__.ipynb).
-#nb # HTML output can be viewed [here](https://juliagaussianprocesses.github.io/KernelFunctions.jl/dev/examples/@__NAME__/).
+#md # The corresponding notebook can be viewed in [nbviewer](@__NBVIEWER_ROOT_URL__/examples/@__NAME__.ipynb).*
+#nb # The rendered HTML can be viewed [in the docs](https://juliagaussianprocesses.github.io/KernelFunctions.jl/dev/examples/@__NAME__/).*
 #
         """,
     )

docs/make.jl

@@ -1,4 +1,4 @@
-# run examples
+### Process examples
 const EXAMPLES_SRC = joinpath(@__DIR__, "..", "examples")
 const EXAMPLES_OUT = joinpath(@__DIR__, "src", "examples")
 const LITERATEJL = joinpath(@__DIR__, "literate.jl")
@@ -24,10 +24,12 @@ end
 # Check that all examples were run successfully
 isempty(processes) || success(processes) || error("some examples were not run successfully")
 
-# Build documentation
-using KernelFunctions
+### Build documentation
 using Documenter
 
+using KernelFunctions
+using PDMats, Kronecker  # we have to load all optional packages to generate the full API documentation
+
 # Print `@debug` statements (https://github.com/JuliaDocs/Documenter.jl/issues/955)
 if haskey(ENV, "GITHUB_ACTIONS")
     ENV["JULIA_DEBUG"] = "Documenter"
@@ -39,10 +41,7 @@ DocMeta.setdocmeta!(
     :DocTestSetup,
     quote
         using KernelFunctions
-        using LinearAlgebra
-        using Random
-        using PDMats: PDMats
-    end;
+    end;  # we have to load all packages used (implicitly) within jldoctest blocks in the API docstrings
     recursive=true,
 )
 

docs/src/create_kernel.md

@@ -10,7 +10,7 @@ Here are a few ways depending on how complicated your kernel is:
 
 If your kernel function is of the form `k(x, y) = f(d(x, y))` where `d(x, y)` is a `PreMetric`,
 you can construct your custom kernel by defining `kappa` and `metric` for your kernel.
-Here is for example how one can define the `SqExponentialKernel` again :
+Here is for example how one can define the `SqExponentialKernel` again:
 
 ```julia
 struct MyKernel <: KernelFunctions.SimpleKernel end

examples/README.md

@@ -0,0 +1,52 @@
+# Example notebooks
+
+The examples in this directory are stored in [Literate.jl](https://github.com/fredrikekre/Literate.jl) format.
+
+To run them locally, navigate to the directory with the example that you want to run and
+start the Julia REPL and activate the project environment of the example:
+```julia
+julia> ] activate .
+```
+Alternatively, you can start Julia with `julia --project=.`. Then install all required
+packages with
+```julia
+julia> ] instantiate
+```
+Afterwards simply run
+```julia
+julia> include("script.jl")
+```
+In particular when editing an example, it can be convenient to (re-)run only some parts of
+an example.
+Many editors with Julia support such as VSCode, Juno, and Emacs support the evaluation of individual lines or code chunks.
+
+You can convert a notebook to markdown and Jupyter notebook formats, respectively, by executing
+```julia
+julia> using Literate
+julia> Literate.markdown("script.jl", "output_directory")
+julia> Literate.notebook("script.jl", "output_directory")
+```
+(see the [Literate.jl docs](https://fredrikekre.github.io/Literate.jl/v2/) for additional options) or run
+```shell
+julia docs/literate.jl examples/myexample/script.jl output_directory
+```
+which also executes the code and generates embedded plots etc. in the same way as in building the KernelFunctions documentation.
+
+## Add a new example
+
+Create a new subdirectory in here, and put your code in a file called `script.jl` so that it will get picked up by the automatic docs build.
+
+Every example uses a separate project environment. Therefore you should also create a new
+project environment in the directory of the example that contains all packages required by your script.
+Note that the dependencies of your example *must* include the `Literate` package.
+
+From a Julia REPL started in your example script's directory, you can run
+```julia
+julia> ] activate .
+julia> ] add Literate
+julia> ] add KernelFunctions
+julia> # add any other example-specific dependencies
+```
+to generate the project files.
+
+Make sure to commit both the `Project.toml` and the `Manifest.toml` file when you want to contribute your example in a pull request.