Add docs and update actions

.github/dependabot.yml

@@ -0,0 +1,7 @@
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"

.github/workflows/CI.yml

@@ -1,11 +1,9 @@
 name: CI
 on:
   pull_request:
-    branches:
-      - master
+    branches: [master]
   push:
-    branches:
-      - master
+    branches: [master]
     tags: '*'
 jobs:
   test:
@@ -23,7 +21,7 @@ jobs:
         arch:
           - x64
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: julia-actions/setup-julia@latest
         with:
           version: ${{ matrix.version }}
@@ -32,28 +30,7 @@ jobs:
       - uses: julia-actions/julia-buildpkg@latest
       - uses: julia-actions/julia-runtest@latest
       - uses: julia-actions/julia-processcoverage@latest
-      - uses: codecov/codecov-action@v3
+      - uses: codecov/codecov-action@v5
         with:
-          file: lcov.info
-#   docs:
-#     name: Documentation
-#     runs-on: ubuntu-latest
-#     steps:
-#       - uses: actions/checkout@v2
-#       - uses: julia-actions/setup-julia@v1
-#         with:
-#           version: '1'
-#       - run: |
-#           julia --project=docs -e '
-#             using Pkg
-#             Pkg.develop(PackageSpec(path=pwd()))
-#             Pkg.instantiate()'
-#       - run: |
-#           julia --project=docs -e '
-#             using Documenter: doctest
-#             using MYPACKAGE
-#             doctest(MYPACKAGE)' # change MYPACKAGE to the name of your package
-#       - run: julia --project=docs docs/make.jl
-#         env:
-#           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-#           DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
+          files: lcov.info
+          token: ${{ secrets.CODECOV_TOKEN }}

.github/workflows/docs.yml

@@ -0,0 +1,20 @@
+name: Documentation
+on:
+  pull_request:
+    branches: [master]
+  push:
+    branches: [master]
+    tags: '*'
+jobs:
+   documenter:
+     name: Build Documentation
+     runs-on: ubuntu-latest
+     steps:
+       - uses: actions/checkout@v4
+       - uses: julia-actions/setup-julia@v2
+         with:
+           version: '1'
+       - uses: julia-actions/cache@v2
+       - uses: julia-actions/julia-docdeploy@v1
+         env:
+           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -1,2 +1,3 @@
 examples/.ipynb_checkpoints/*
-Manifest.toml
+Manifest.toml
+docs/build/

docs/Project.toml

@@ -0,0 +1,9 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+KernelDensity = "5ab0869b-81aa-558d-bb23-cbf5423bbe9b"
+
+[compat]
+Documenter = "1"
+
+[sources.KernelDensity]
+path = ".."

docs/make.jl

@@ -0,0 +1,11 @@
+using Documenter
+using KernelDensity
+
+makedocs(
+    sitename = "KernelDensity.jl",
+    modules = [KernelDensity],
+)
+deploydocs(
+    repo = "github.com/JuliaStats/KernelDensity.jl.git",
+    push_preview = true,
+)

docs/src/index.md

@@ -0,0 +1,108 @@
+```@meta
+CurrentModule = KernelDensity
+```
+
+# KernelDensity.jl
+
+Kernel density estimators for Julia.
+
+## Usage
+
+### Univariate
+The main accessor function is `kde`:
+
+```julia
+U = kde(data)
+```
+
+will construct a `UnivariateKDE` object from the real vector `data`. The
+optional keyword arguments are
+* `boundary`: the lower and upper limits of the kde as a tuple. Due to the
+  fourier transforms used internally, there should be sufficient spacing to
+  prevent wrap-around at the boundaries.
+* `npoints`: the number of interpolation points to use. The function uses
+  fast Fourier transforms (FFTs) internally, so for optimal efficiency this
+  should be a power of 2 (default = 2048).
+* `kernel`: the distributional family from
+  [Distributions.jl](https://github.com/JuliaStats/Distributions.jl) to use as
+  the kernel (default = `Normal`). To add your own kernel, extend the internal
+  `kernel_dist` function.
+* `bandwidth`: the bandwidth of the kernel. Default is to use Silverman's
+  rule.
+
+The `UnivariateKDE` object `U` contains gridded coordinates (`U.x`) and the density
+estimate (`U.density`). These are typically sufficient for plotting.
+A related function
+
+``` kde_lscv(data) ```
+
+will construct a `UnivariateKDE` object, with the bandwidth selected by
+least-squares cross validation. It accepts the above keyword arguments, except
+`bandwidth`.
+
+
+There are also some slightly more advanced interfaces:
+```julia
+kde(data, midpoints::R) where R<:AbstractRange
+```
+allows specifying the internal grid to use. Optional keyword arguments are
+`kernel` and `bandwidth`.
+
+```julia
+kde(data, dist::Distribution)
+```
+allows specifying the exact distribution to use as the kernel. Optional
+keyword arguments are `boundary` and `npoints`.
+
+```julia
+kde(data, midpoints::R, dist::Distribution) where R<:AbstractRange
+```
+allows specifying both the distribution and grid.
+
+### Bivariate
+
+The usage mirrors that of the univariate case, except that `data` is now
+either a tuple of vectors
+```julia
+B = kde((xdata, ydata))
+```
+or a matrix with two columns
+```julia
+B = kde(datamatrix)
+```
+Similarly, the optional arguments all now take tuple arguments:
+e.g. `boundary` now takes a tuple of tuples `((xlo,xhi),(ylo,yhi))`.
+
+The `BivariateKDE` object `B` contains gridded coordinates (`B.x` and `B.y`) and the bivariate density
+estimate (`B.density`).
+
+### Interpolation
+
+The KDE objects are stored as gridded density values, with attached
+coordinates. These are typically sufficient for plotting (see above), but
+intermediate values can be interpolated using the
+[Interpolations.jl](https://github.com/tlycken/Interpolations.jl) package via the `pdf` method
+(extended from Distributions.jl).
+
+```julia
+pdf(k::UnivariateKDE, x)
+pdf(k::BivariateKDE, x, y)
+```
+
+where `x` and `y` are real numbers or arrays.
+
+If you are making multiple calls to `pdf`, it will be more efficient to
+construct an intermediate `InterpKDE` to store the interpolation structure:
+
+```julia
+ik = InterpKDE(k)
+pdf(ik, x)
+```
+
+`InterpKDE` will pass any extra arguments to `interpolate`.
+
+## API Reference
+
+```@autodocs
+Modules = [KernelDensity]
+```