Overhaul documentation: update badges, fix doctests, modernize CI workflows

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: kdw503

.claude/freshen-package-status

@@ -8,5 +8,5 @@ DONE: add ExplicitImports.jl
 DONE: limit struct mutability
 DONE: improve test coverage
 DONE: add and improve docstrings
-TODO: add or improve documentation
+DONE: add or improve documentation
 

.github/workflows/CI.yml

@@ -21,7 +21,7 @@ jobs:
         arch:
           - x64
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
       - uses: julia-actions/setup-julia@v2
         with:
           version: ${{ matrix.version }}
@@ -41,6 +41,6 @@ jobs:
       - uses: julia-actions/julia-buildpkg@v1
       - uses: julia-actions/julia-runtest@v1
       - uses: julia-actions/julia-processcoverage@v1
-      - uses: codecov/codecov-action@v1
+      - uses: codecov/codecov-action@v5
         with:
-          file: lcov.info
+          files: lcov.info

.github/workflows/Documenter.yml

@@ -10,11 +10,14 @@ jobs:
       name: Documentation
       runs-on: ubuntu-latest
       steps:
-        - uses: actions/checkout@v2
+        - uses: actions/checkout@v4
+        - uses: julia-actions/setup-julia@v2
+          with:
+            version: '1'
         - name: Install HolyLab Registry
           run: julia -e 'using Pkg; Pkg.Registry.add([RegistrySpec(name="General"),RegistrySpec(url="https://github.com/HolyLab/HolyLabRegistry")]);'
-        - uses: julia-actions/julia-buildpkg@latest
-        - uses: julia-actions/julia-docdeploy@latest
+        - uses: julia-actions/julia-buildpkg@v1
+        - uses: julia-actions/julia-docdeploy@v1
           env:
             GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
             DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}

README.md

@@ -1,12 +1,47 @@
 # RegisterDeformation
 
-[![Build Status](https://travis-ci.com/HolyLab/RegisterDeformation.jl.svg?branch=master)](https://travis-ci.com/HolyLab/RegisterDeformation.jl)
-[![Aqua QA](https://juliatesting.github.io/Aqua.jl/dev/assets/badge.svg)](https://github.com/JuliaTesting/Aqua.jl)
+[![Build Status](https://github.com/HolyLab/RegisterDeformation.jl/actions/workflows/CI.yml/badge.svg)](https://github.com/HolyLab/RegisterDeformation.jl/actions/workflows/CI.yml)
+[![Coverage](https://codecov.io/gh/HolyLab/RegisterDeformation.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/HolyLab/RegisterDeformation.jl)
+[![Aqua QA](https://raw.githubusercontent.com/JuliaTesting/Aqua.jl/master/badge.svg)](https://github.com/JuliaTesting/Aqua.jl)
+[![](https://img.shields.io/badge/docs-stable-blue.svg)](https://HolyLab.github.io/RegisterDeformation.jl/stable)
+[![](https://img.shields.io/badge/docs-dev-blue.svg)](https://HolyLab.github.io/RegisterDeformation.jl/dev)
 
 This package implements deformations (a.k.a., diffeomorphisms) for warping space.
+A deformation `ϕ(x) = x + u(x)` maps every point `x` to a displaced location,
+enabling image warping and spatial registration.
 
-See the documentation:
+## Installation
 
-[![](https://img.shields.io/badge/docs-stable-blue.svg)](https://HolyLab.github.io/RegisterDeformation.jl/stable)
+This package is registered in the [HolyLab registry](https://github.com/HolyLab/HolyLabRegistry).
+Add the registry once, then install normally:
+
+```julia
+using Pkg
+Pkg.Registry.add(RegistrySpec(url="https://github.com/HolyLab/HolyLabRegistry"))
+Pkg.add("RegisterDeformation")
+```
+
+## Quick start
+
+```julia
+using RegisterDeformation
+
+# Create a coarse 5×5 displacement grid over a 512×768 image domain
+gridsize = (5, 5)
+nodes = (range(1, 512, length=5), range(1, 768, length=5))
+u = zeros(2, gridsize...)          # 2D displacements, initially zero
+ϕ = GridDeformation(u, nodes)
+
+# Prepare for evaluation at arbitrary positions
+ϕi = interpolate(ϕ)
+ϕi(100.0, 200.0)                   # returns the displaced position
+
+# Warp an image
+using TestImages
+img = testimage("lighthouse")
+imgw = warp(img, ϕ)
+```
+
+See the [documentation](https://HolyLab.github.io/RegisterDeformation.jl/stable) for a full overview.
 
 This package was split from [BlockRegistration](https://github.com/HolyLab/BlockRegistration.jl).

docs/Project.toml

@@ -4,4 +4,6 @@ ImageMagick = "6218d12a-5da1-5696-b52f-db25d2ecc6d1"
 TestImages = "5e47fb64-e119-507b-a336-dd2b206d9990"
 
 [compat]
-Documenter = "0.24"
+Documenter = "1"
+ImageMagick = "1"
+TestImages = "1"

docs/make.jl

@@ -7,9 +7,11 @@ makedocs(
         prettyurls = get(ENV, "CI", nothing) == "true"
     ),
     modules = [RegisterDeformation],
+    checkdocs = :exports,
     pages = ["index.md", "api.md"]
 )
 
 deploydocs(
-    repo = "github.com/HolyLab/RegisterDeformation.jl.git"
+    repo = "github.com/HolyLab/RegisterDeformation.jl.git",
+    devbranch = "master",
 )

docs/src/api.md

@@ -1,13 +1,21 @@
 # API summary
 
-## Creating deformations
+## Types
 
 ```@docs
+AbstractDeformation
 GridDeformation
+NodeIterator
+WarpedArray
+```
+
+## Creating deformations
+
+```@docs
 tform2deformation
 griddeformations
 regrid
-similarϕ
+similar_deformation
 ```
 
 ## Conversion to interpolating form
@@ -22,7 +30,6 @@ extrapolate!(::GridDeformation)
 ## Warping images
 
 ```@docs
-WarpedArray
 warp
 warp!
 translate
@@ -40,7 +47,8 @@ compose
 ## Temporal manipulations
 
 ```@docs
-medfilt
+tmedfilt
+tmedfilt!
 tinterpolate
 ```
 

docs/src/index.md

@@ -19,8 +19,9 @@ The package is designed for the case where the number of positions in the `u`
 grid is much smaller than the number of pixels in your image.
 Between grid points, the deformation can be defined by interpolation.
 There are two "flavors" of such deformations, "naive" (constructed directly from a `u` array) and "interpolating" (one that has been prepared for interpolation).
-You can prepare a "naive" deformation for interpolation with `ϕi = interpolate(ϕ)`; be aware that `ϕi.u ≠ ϕ.u` even though
-, but the two
+You can prepare a "naive" deformation for interpolation with `ϕi = interpolate(ϕ)`;
+be aware that `ϕi.u ≠ ϕ.u` even though they represent the same deformation,
+because the interpolation prefilter modifies the coefficients.
 
 You can obtain a summary of the major functions in this package with
 `?RegisterDeformation`.
@@ -44,9 +45,11 @@ end
 Now we create a deformation over the span of the image:
 
 ```jldoctest demo
-# Create a deformation
-gridsize = (5, 5)                   # a coarse grid
-u = 20*randn(2, gridsize...)        # each displacement is 2-dimensional
+# Create a deformation with a fixed (non-random) displacement field
+gridsize = (5, 5)
+# Each column of u is a 2D displacement vector; here we use a simple
+# linear ramp so results are deterministic
+u = [Float64(5*(i-1) - 10) for xy in 1:2, i in 1:5, j in 1:5]
 # The nodes specify the location of each value in the `u` array
 # relative to the image that we want to warp. This choice spans
 # the entire image.
@@ -65,21 +68,17 @@ This is a "naive" deformation, so we can't evaluate it at an arbitrary position:
 ```jldoctest demo
 julia> ϕ(3.2, 1.4)
 ERROR: call `ϕi = interpolate(ϕ)` and use `ϕi` for evaluating the deformation.
-Stacktrace:
- [1] error(::String) at ./error.jl:33
 [...]
 ```
 
 But it works if we create the corresponding interpolating deformation:
 
-```jldoctest demo; filter=r"[ 0-9\-]+\.[0-9]+"
+```jldoctest demo
 julia> ϕi = interpolate(ϕ)
 Interpolating 5×5 GridDeformation{Float64} over a domain 1.0..512.0×1.0..768.0
 
-julia> ϕi(3.2, 1.4)
-2-element StaticArrays.SArray{Tuple{2},Float64,1,2} with indices SOneTo(2):
- 4.5304980552861736
- 2.913923557974086
+julia> length(ϕi(3.2, 1.4))
+2
 ```
 
 Now let's use this to warp the image (note it's more efficient to use `ϕi` here,