Build documentation more strictly (#239)

devmotion · web-flow · commit 0ff876108b3f · 2021-01-19T21:32:11.000+01:00
diff --git a/Project.toml b/Project.toml
@@ -1,6 +1,6 @@
 name = "KernelFunctions"
 uuid = "ec8451be-7e33-11e9-00cf-bbf324bd1392"
-version = "0.8.17"
+version = "0.8.18"
 
 [deps]
 Compat = "34da2185-b29b-5c13-b0c7-acf172513d20"
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -1,5 +1,7 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+PDMats = "90014a1f-27ba-587c-ab20-58faa44d9150"
 
 [compat]
 Documenter = "0.23, 0.24, 0.25, 0.26"
+PDMats = "0.10"
diff --git a/docs/make.jl b/docs/make.jl
@@ -1,10 +1,21 @@
 using Documenter
+
+# Print `@debug` statements (https://github.com/JuliaDocs/Documenter.jl/issues/955)
+if haskey(ENV, "GITHUB_ACTIONS")
+    ENV["JULIA_DEBUG"] = "Documenter"
+end
+
 using KernelFunctions
 
 DocMeta.setdocmeta!(
     KernelFunctions,
     :DocTestSetup,
-    :(using KernelFunctions, LinearAlgebra, Random);
+    quote
+        using KernelFunctions
+        using LinearAlgebra
+        using Random
+        using PDMats: PDMats
+    end;
     recursive=true,
 )
 
@@ -14,15 +25,17 @@ makedocs(;
     modules=[KernelFunctions],
     pages=[
         "Home" => "index.md",
-        "User Guide" => "userguide.md",
-        "Examples" => "example.md",
-        "Kernel Functions" => "kernels.md",
-        "Input Transforms" => "transform.md",
-        "Metrics" => "metrics.md",
-        "Theory" => "theory.md",
-        "Custom Kernels" => "create_kernel.md",
+        "userguide.md",
+        "kernels.md",
+        "transform.md",
+        "metrics.md",
+        "theory.md",
+        "create_kernel.md",
         "API" => "api.md",
+        "Examples" => "example.md",
     ],
+    strict=true,
+    checkdocs=:exports,
 )
 
 deploydocs(;
diff --git a/docs/src/api.md b/docs/src/api.md
@@ -17,9 +17,7 @@ kernelmatrix!
 kerneldiagmatrix
 kerneldiagmatrix!
 kernelpdmat
-kernelkronmat
 nystrom
-transform
 ```
 
 ## Utilities
diff --git a/docs/src/create_kernel.md b/docs/src/create_kernel.md
@@ -1,3 +1,5 @@
+# Custom Kernels
+
 ## Creating your own kernel
 
 KernelFunctions.jl contains the most popular kernels already but you might want to make your own!
diff --git a/docs/src/kernels.md b/docs/src/kernels.md
@@ -120,7 +120,7 @@ of kernels together.
 TransformedKernel
 transform(::Kernel, ::Transform)
 transform(::Kernel, ::Real)
-transform(::Kernel, ::AbstractVector{<:Real})
+transform(::Kernel, ::AbstractVector)
 ScaledKernel
 KernelSum
 KernelProduct
diff --git a/docs/src/theory.md b/docs/src/theory.md
@@ -1 +1,3 @@
+# Theory
+
 See [Uncyclopedia article](https://en.wikipedia.org/wiki/Positive-definite_kernel)
diff --git a/docs/src/userguide.md b/docs/src/userguide.md
@@ -52,7 +52,7 @@ To evaluate the kernel function on two vectors you simply call the kernel object
 ## Creating a kernel matrix
 
 Kernel matrices can be created via the `kernelmatrix` function or `kerneldiagmatrix` for only the diagonal.
-An important argument to give is the data layout of the input `obsdim`. It specifies whether the number of observed data points is along the first dimension (`obsdim=1`, i.e. the matrix shape is number of samples times number of features) or along the second dimension (`obsdim=2`, i.e. the matrix shape is number of features times number of samples), similarly to [Distances.jl](https://github.com/JuliaStats/Distances.jl). If not given explicitly, `obsdim` defaults to [`defaultobs`](@ref).
+An important argument to give is the data layout of the input `obsdim`. It specifies whether the number of observed data points is along the first dimension (`obsdim=1`, i.e. the matrix shape is number of samples times number of features) or along the second dimension (`obsdim=2`, i.e. the matrix shape is number of features times number of samples), similarly to [Distances.jl](https://github.com/JuliaStats/Distances.jl). If not given explicitly, `obsdim` defaults to `2`.
 For example:
 ```julia
   k = SqExponentialKernel()
diff --git a/src/KernelFunctions.jl b/src/KernelFunctions.jl
@@ -1,7 +1,3 @@
-"""
-KernelFunctions. [Github](https://github.com/JuliaGaussianProcesses/KernelFunctions.jl)
-[Documentation](https://juliagaussianprocesses.github.io/KernelFunctions.jl/stable/)
-"""
 module KernelFunctions
 
 if !isfile(joinpath(@__DIR__, "update_v0.8.0"))
diff --git a/test/Project.toml b/test/Project.toml
@@ -1,6 +1,7 @@
 [deps]
 AxisArrays = "39de3d68-74b9-583c-8d2d-e117c070f3a9"
 Distances = "b4f34e82-e78d-54a5-968a-f98e89d6e8f7"
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 FiniteDifferences = "26cc04aa-876d-5657-8c51-4c34ba976000"
 Flux = "587475ba-b771-5e3f-ad9e-33799f191a9c"
 ForwardDiff = "f6369f11-7733-5829-9624-2563aa707210"
@@ -17,6 +18,7 @@ Zygote = "e88e6eb3-aa80-5325-afca-941959d7151f"
 [compat]
 AxisArrays = "0.4.3"
 Distances = "0.9, 0.10"
+Documenter = "0.25"
 FiniteDifferences = "0.10.8, 0.11, 0.12"
 Flux = "0.10, 0.11"
 ForwardDiff = "0.10"
diff --git a/test/runtests.jl b/test/runtests.jl
@@ -1,6 +1,7 @@
 using KernelFunctions
 using AxisArrays
 using Distances
+using Documenter
 using Kronecker
 using LinearAlgebra
 using PDMats
@@ -145,4 +146,19 @@ include("test_utils.jl")
 
     include("generic.jl")
     include("zygote_adjoints.jl")
+
+    @testset "doctests" begin
+        DocMeta.setdocmeta!(
+            KernelFunctions,
+            :DocTestSetup,
+            quote
+                using KernelFunctions
+                using LinearAlgebra
+                using Random
+                using PDMats: PDMats
+            end;
+            recursive=true,
+        )
+        doctest(KernelFunctions)
+    end
 end

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+# Custom Kernels`
	`2`	`+`
`1`	`3`	`## Creating your own kernel`
`2`	`4`
`3`	`5`	`KernelFunctions.jl contains the most popular kernels already but you might want to make your own!`
Original file line number	Diff line number	Diff line change
`@@ -1 +1,3 @@`
	`1`	`+# Theory`
	`2`	`+`
`1`	`3`	`See [Uncyclopedia article](https://en.wikipedia.org/wiki/Positive-definite_kernel)`