Tweak some docs a bit (#311)

* Tweak some docs a bit

* Update docs/src/index.md

Co-authored-by: Théo Galy-Fajou <[email protected]>

* Update docs/src/userguide.md

Co-authored-by: Théo Galy-Fajou <[email protected]>

* Update docs/src/userguide.md

Co-authored-by: Théo Galy-Fajou <[email protected]>

Author: willtebbutt

docs/make.jl

@@ -29,7 +29,6 @@ makedocs(;
         "kernels.md",
         "transform.md",
         "metrics.md",
-        "theory.md",
         "create_kernel.md",
         "API" => "api.md",
         "Examples" => "example.md",

docs/src/index.md

@@ -1,17 +1,12 @@
 # KernelFunctions.jl
 
-Model-agnostic kernel functions compatible with automatic differentiation
-
-**KernelFunctions.jl** is a general purpose kernel package.
+**KernelFunctions.jl** is a general purpose [kernel](https://en.wikipedia.org/wiki/Positive-definite_kernel) package.
 It aims at providing a flexible framework for creating kernels and manipulating them.
-The main goals of this package compared to its predecessors/concurrents in [MLKernels.jl](https://github.com/trthatcher/MLKernels.jl), [Stheno.jl](https://github.com/willtebbutt/Stheno.jl), [GaussianProcesses.jl](https://github.com/STOR-i/GaussianProcesses.jl) and [AugmentedGaussianProcesses.jl](https://github.com/theogf/AugmentedGaussianProcesses.jl) are:
-- **Automatic Differentation** compatibility: all kernel functions should be differentiable via packages like [ForwardDiff.jl](https://github.com/JuliaDiff/ForwardDiff.jl) or [Zygote.jl](https://github.com/FluxML/Zygote.jl)
+The main goals of this package are:
 - **Flexibility**: operations between kernels should be fluid and easy without breaking.
 - **Plug-and-play**: including the kernels before/after other steps should be straightforward.
+- **Automatic Differentation** compatibility: all kernel functions which _ought_ to be differentiable using AD packages like [ForwardDiff.jl](https://github.com/JuliaDiff/ForwardDiff.jl) or [Zygote.jl](https://github.com/FluxML/Zygote.jl) _should_ be.
 
-The methodology of how kernels are computed is quite simple and is done in three phases :
-- A `Transform` object is applied sample-wise on every sample
-- The pairwise matrix is computed using [Distances.jl](https://github.com/JuliaStats/Distances.jl) by using a `Metric` proper to each kernel
-- The `Kernel` function is applied element-wise on the pairwise matrix
+This package builds on of lots of excellent existing work in packages such as [MLKernels.jl](https://github.com/trthatcher/MLKernels.jl), [Stheno.jl](https://github.com/willtebbutt/Stheno.jl), [GaussianProcesses.jl](https://github.com/STOR-i/GaussianProcesses.jl), and [AugmentedGaussianProcesses.jl](https://github.com/theogf/AugmentedGaussianProcesses.jl).
 
-For a quick introduction on how to use it go to [User guide](@ref)
+See the [User guide](@ref) for a brief introduction.

docs/src/theory.md

@@ -73,18 +73,37 @@ kernelmatrix(k, ColVecs(X))  # returns a 5×5 matrix -- each column of X treated
 ```
 This is the mechanism used throughout KernelFunctions.jl to handle multi-dimensional inputs.
 
-You can also utilise the `obsdim` keyword argument if you prefer:
+You can utilise the `obsdim` keyword argument if you prefer:
 ```julia
 kernelmatrix(k, X; obsdim=1) # same as RowVecs(X)
 kernelmatrix(k, X; obsdim=2) # same as ColVecs(X)
 ```
 This is similar to the convention used in [Distances.jl](https://github.com/JuliaStats/Distances.jl).
 
-See [Input Types](@ref) for a more thorough discussion of these two approaches.
+### So what type should I use to represent a collection of inputs?
+The central assumption made by KernelFunctions.jl is that all collections of `N` inputs are represented by `AbstractVector`s of length `N`.
+Abstraction is then used to ensure that efficiency is retained, `ColVecs` and `RowVecs`
+being the most obvious examples of this.
 
+Concretely:
+1. For `Real`-valued inputs (scalars), a `Vector{<:Real}` is fine.
+1. For vector-valued inputs, consider a `ColVecs` or `RowVecs`.
+1. For a new input type, simply represent collections of inputs of this type as an `AbstractVector`.
 
+See [Input Types](@ref) and [Design](@ref) for a more thorough discussion of the
+considerations made when this design was adopted.
 
-We also support specific kernel matrix outputs:
+The `obsdim` kwarg mentioned above is a special case for vector-valued inputs stored in a
+matrix.
+It is implemented as a lightweight wrapper that constructs either a `RowVecs` or `ColVecs`
+from your inputs, and passes this on.
+
+
+
+### Output Types
+
+In addition to plain `Matrix`-like output, KernelFunctions.jl supports specific output
+types:
 - For a positive-definite matrix object of type `PDMat` from [`PDMats.jl`](https://github.com/JuliaStats/PDMats.jl), you can call the following:
 ```julia
 using PDMats

docs/src/userguide.md

@@ -24,9 +24,16 @@ kernelmatrix!
 
 """
     kernelmatrix(κ::Kernel, x::AbstractVector)
+
+Compute the kernel `κ` for each pair of inputs in `x`.
+Returns a matrix of size `(length(x), length(x))` satisfying
+`kernelmatrix(κ, x)[p, q] == κ(x[p], x[q])`.
+
     kernelmatrix(κ::Kernel, x::AbstractVector, y::AbstractVector)
 
-Calculate the kernel matrix of `x` (and `y`) with respect to kernel `κ`.
+Compute the kernel `κ` for each pair of inputs in `x` and `y`.
+Returns a matrix of size `(length(x), length(y))` satisfying
+`kernelmatrix(κ, x, y)[p, q] == κ(x[p], y[q])`.
 
     kernelmatrix(κ::Kernel, X::AbstractMatrix; obsdim::Int=2)
     kernelmatrix(κ::Kernel, X::AbstractMatrix, Y::AbstractMatrix; obsdim::Int=2)
@@ -65,11 +72,11 @@ kernelmatrix_diag!
 """
     kernelmatrix_diag(κ::Kernel, x::AbstractVector)
 
-Calculate the diagonal matrix of `x` with respect to kernel `κ`.
+Compute the diagonal of `kernelmatrix(κ, x)` efficiently.
 
     kernelmatrix_diag(κ::Kernel, x::AbstractVector, y::AbstractVector)
 
-Calculate the diagonal of `kernelmatrix(κ, x, y)` efficiently.
+Compute the diagonal of `kernelmatrix(κ, x, y)` efficiently.
 Requires that `x` and `y` are the same length.
 
     kernelmatrix_diag(κ::Kernel, X::AbstractMatrix; obsdim::Int=2)