Package maintenance: Aqua, ExplicitImports, coverage, docstrings, docs

.github/workflows/CI.yml

@@ -45,3 +45,20 @@ jobs:
         with:
           file: lcov.info
           token: ${{ secrets.CODECOV_TOKEN }}
+  docs:
+    name: Documentation
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@v2
+        with:
+          version: '1'
+      - name: registry_add
+        run: julia -e 'using Pkg; pkg"registry add General https://github.com/HolyLab/HolyLabRegistry.git"'
+      - uses: julia-actions/julia-buildpkg@v1
+      - uses: julia-actions/julia-docdeploy@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}

Project.toml

@@ -1,7 +1,7 @@
 name = "RegisterMismatch"
 uuid = "3c0dd727-6833-5f5d-a1e8-c0d421935c74"
+version = "1.0.0"
 authors = ["Tim Holy <tim.holy@gmail.com>"]
-version = "0.4.2"
 
 [deps]
 FFTW = "7a1cc6ca-52ef-59f5-83cd-3a7055c09341"
@@ -15,21 +15,32 @@ RegisterCore = "67712758-55e7-5c3c-8e85-dda1d7758434"
 RegisterMismatchCommon = "abb2e897-52bf-5d28-a379-6ca321e3b878"
 
 [compat]
+Aqua = "0.8"
+CenterIndexedArrays = "1"
+Documenter = "1"
+ExplicitImports = "1"
 FFTW = "0.3, 1"
 ImageCore = "0.8.1, 0.9, 0.10"
+ImageFiltering = "0.7"
+Libdl = "1"
 MappedArrays = "0.2, 0.3, 0.4"
 PaddedViews = "0.5"
+Printf = "1"
 RFFT = "0.1, 1"
 Reexport = "0.2, 1"
 RegisterCore = "0.2.1, 1"
 RegisterMismatchCommon = "0.2.2, 1"
+Test = "1"
 julia = "1.10"
 
 [extras]
+Aqua = "4c88cf16-eb10-579e-8560-4a9242c79595"
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 CenterIndexedArrays = "46a7138f-0d70-54e1-8ada-fb8296f91f24"
+ExplicitImports = "7d51a73a-1435-4ff3-83d9-f097790105c7"
 ImageFiltering = "6a3955dd-da59-5b1f-98d4-e7296123deb5"
 Libdl = "8f399da3-3557-5675-b5ff-fb832c97cbdb"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [targets]
-test = ["Test", "CenterIndexedArrays", "ImageFiltering", "Libdl"]
+test = ["Aqua", "Documenter", "ExplicitImports", "Test", "CenterIndexedArrays", "ImageFiltering", "Libdl"]

README.md

@@ -0,0 +1,46 @@
+# RegisterMismatch.jl
+
+[![CI](https://github.com/HolyLab/RegisterMismatch.jl/actions/workflows/CI.yml/badge.svg)](https://github.com/HolyLab/RegisterMismatch.jl/actions/workflows/CI.yml)
+[![Coverage](https://codecov.io/gh/HolyLab/RegisterMismatch.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/HolyLab/RegisterMismatch.jl)
+[![Stable docs](https://img.shields.io/badge/docs-stable-blue.svg)](https://HolyLab.github.io/RegisterMismatch.jl/stable)
+[![Dev docs](https://img.shields.io/badge/docs-dev-blue.svg)](https://HolyLab.github.io/RegisterMismatch.jl/dev)
+
+FFT-based image mismatch computation for translation-based image registration.
+This package is the CPU backend in the
+[HolyLab](https://github.com/HolyLab) image registration stack; a GPU
+counterpart is provided by
+[RegisterMismatchCuda.jl](https://github.com/HolyLab/RegisterMismatchCuda.jl).
+
+## Installation
+
+This package is registered in the
+[HolyLabRegistry](https://github.com/HolyLab/HolyLabRegistry).
+Add the registry once, then install as usual:
+
+```julia
+using Pkg
+pkg"registry add General https://github.com/HolyLab/HolyLabRegistry.git"
+Pkg.add("RegisterMismatch")
+```
+
+## Quick start
+
+```julia
+using RegisterMismatch
+
+# Two images, moving shifted by (2, 3) relative to fixed
+fixed  = zeros(Float32, 32, 32); fixed[10:22, 10:22] .= 1f0
+moving = circshift(fixed, (2, 3))
+
+# Find the optimal integer-pixel shift
+shift = register_translate(fixed, moving, (5, 5))
+# CartesianIndex(2, 3)
+```
+
+For non-uniform or large displacements, use `mismatch_apertures` to obtain a
+grid of local mismatches and recover a smooth displacement field.
+
+See the [documentation](https://HolyLab.github.io/RegisterMismatch.jl/stable)
+for a full guide, including preprocessing (`highpass`, `nanpad`),
+aperture-based registration, bias correction, and the low-level `CMStorage`
+workflow for repeated computations against the same fixed image.

docs/Project.toml

@@ -0,0 +1,13 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+FFTW = "7a1cc6ca-52ef-59f5-83cd-3a7055c09341"
+RegisterCore = "67712758-55e7-5c3c-8e85-dda1d7758434"
+RegisterMismatch = "3c0dd727-6833-5f5d-a1e8-c0d421935c74"
+RegisterMismatchCommon = "abb2e897-52bf-5d28-a379-6ca321e3b878"
+
+[compat]
+Documenter = "1"
+FFTW = "1"
+RegisterCore = "1"
+RegisterMismatchCommon = "1"
+julia = "1.10"

docs/make.jl

@@ -0,0 +1,34 @@
+using Documenter
+using RegisterMismatch
+using RegisterCore
+using RegisterMismatchCommon
+using FFTW
+
+DocMeta.setdocmeta!(RegisterMismatch, :DocTestSetup, :(using RegisterMismatch, RegisterCore, FFTW); recursive = true)
+DocMeta.setdocmeta!(RegisterMismatchCommon, :DocTestSetup, :(using RegisterMismatchCommon); recursive = true)
+DocMeta.setdocmeta!(RegisterCore, :DocTestSetup, :(using RegisterCore); recursive = true)
+
+makedocs(;
+    modules = [RegisterMismatch, RegisterMismatchCommon, RegisterCore],
+    sitename = "RegisterMismatch.jl",
+    format = Documenter.HTML(;
+        prettyurls = get(ENV, "CI", "false") == "true",
+        canonical = "https://HolyLab.github.io/RegisterMismatch.jl",
+        repolink = "https://github.com/HolyLab/RegisterMismatch.jl",
+    ),
+    pages = [
+        "Home" => "index.md",
+        "API Reference" => "api.md",
+    ],
+    checkdocs = :exports,
+    warnonly = false,
+    # upstream packages are installed (not dev'd), so Documenter cannot determine
+    # their git commit; disable source links to avoid MissingRemoteError
+    remotes = nothing,
+)
+
+deploydocs(;
+    repo = "github.com/HolyLab/RegisterMismatch.jl",
+    devbranch = "master",
+    push_preview = true,
+)

docs/src/api.md

@@ -0,0 +1,103 @@
+# API Reference
+
+```@meta
+DocTestSetup = quote
+    using RegisterMismatch, RegisterCore, FFTW
+end
+```
+
+## RegisterMismatch module
+
+```@docs
+RegisterMismatch
+```
+
+## Core mismatch functions
+
+```@docs
+mismatch
+mismatch!
+mismatch_apertures
+mismatch_apertures!
+mismatch0
+```
+
+## Low-level reusable workflow
+
+```@docs
+CMStorage
+fillfixed!
+```
+
+## Preprocessing
+
+```@docs
+highpass
+highpass!
+nanpad
+```
+
+## Post-processing
+
+```@docs
+correctbias!
+truncatenoise!
+```
+
+## Utilities
+
+```@docs
+register_translate
+aperture_grid
+allocate_mmarrays
+aperture_range
+each_point
+set_FFTPROD
+```
+
+## Types and helpers (RegisterCore)
+
+```@docs
+MismatchArray
+NumDenom
+separate
+ratio
+maxshift
+mismatcharrays
+```
+
+## Indexing helpers (RegisterCore)
+
+```@docs
+argmin_mismatch
+paddedview
+trimmedview
+ColonFun
+```
+
+## Preprocessing (RegisterCore)
+
+```@docs
+PreprocessSNF
+```
+
+## Type aliases (RegisterMismatchCommon)
+
+```@docs
+DimsLike
+WidthLike
+```
+
+## Internal helpers
+
+```@docs
+assertsamesize
+checksize_maxshift
+default_aperture_width
+padranges
+padsize
+shiftrange
+tovec
+RegisterMismatchCommon
+RegisterCore
+```