docs: fix build warnings and run doctest as unit test (#234)

johnnychen94 · web-flow · commit 960457a2390f · 2021-10-30T16:51:24.000+08:00
diff --git a/Project.toml b/Project.toml
@@ -35,6 +35,7 @@ julia = "1"
 
 [extras]
 AxisArrays = "39de3d68-74b9-583c-8d2d-e117c070f3a9"
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 ImageIO = "82e4d734-157c-48bb-816b-45c225c6df19"
 ImageMagick = "6218d12a-5da1-5696-b52f-db25d2ecc6d1"
 ImageMetadata = "bc367c6b-8a6b-528e-b4bd-a4b897500b49"
@@ -45,4 +46,4 @@ Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 TestImages = "5e47fb64-e119-507b-a336-dd2b206d9990"
 
 [targets]
-test = ["AxisArrays", "ImageIO", "ImageMagick", "ImageMetadata", "ImageQualityIndexes", "Logging", "Random", "Test", "TestImages"]
+test = ["AxisArrays", "Documenter", "ImageIO", "ImageMagick", "ImageMetadata", "ImageQualityIndexes", "Logging", "Random", "Test", "TestImages"]
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -5,9 +5,11 @@ ImageContrastAdjustment = "f332f351-ec65-5f6a-b3d1-319c6670881a"
 ImageCore = "a09fc81d-aa75-5fe9-8630-4744c3626534"
 ImageDistances = "51556ac3-7006-55f5-8cb3-34580c88182d"
 ImageFiltering = "6a3955dd-da59-5b1f-98d4-e7296123deb5"
+ImageIO = "82e4d734-157c-48bb-816b-45c225c6df19"
 ImageMagick = "6218d12a-5da1-5696-b52f-db25d2ecc6d1"
 ImageMorphology = "787d08f9-d448-5407-9aad-5290dd7ab264"
 ImageShow = "4e3cecfd-b093-5904-9786-8bbb286a6a31"
+OffsetArrays = "6fe1bfb0-de20-5000-8ca7-80f57d26f881"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
diff --git a/docs/make.jl b/docs/make.jl
@@ -1,5 +1,6 @@
 using Documenter, DemoCards
 using ImageFiltering
+using OffsetArrays
 # loading Plots before generating demos (might be helpful to avoid segfaults)
 using Plots
 ENV["GKSwstype"] = "nul" # needed for the GR backend on headless servers
@@ -13,14 +14,20 @@ format = Documenter.HTML(prettyurls = get(ENV, "CI", nothing) == "true",
                          assets = assets)
 
 makedocs(
-    modules  = [ImageFiltering, Kernel, KernelFactors, ImageFiltering.MapWindow],
+    modules  = [ImageFiltering, OffsetArrays, Kernel, KernelFactors, ImageFiltering.MapWindow],
     format   = format,
     sitename = "ImageFiltering",
     pages    = [
         "index.md",
         demos,
         "Function reference" => "function_reference.md"
-    ]
+    ],
+    # Note(johnnychen94): doctest is moved as part of unit test for two reasons:
+    # - we want to run doctest for various Julia versions on various platforms.
+    # - `doctest=true` for `makedocs` will trigger not only doctest of ImageFiltering but also
+    #   that of other packages listed in `modules`. It usually throws warnings that don't
+    #   belong to the scope of this package.
+    doctest = false
 )
 
 demos_cb()
diff --git a/docs/src/function_reference.md b/docs/src/function_reference.md
@@ -46,7 +46,8 @@ KernelFactors.TriggsSdika
 # Kernel utilities
 
 ```@docs
-centered
+OffsetArrays.center
+OffsetArrays.centered
 kernelfactors
 reflect
 ```
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -54,7 +54,7 @@ ability to define arrays whose indices span an arbitrary range:
 
 ```julia
 julia> Kernel.gaussian(1)
-OffsetArrays.OffsetArray{Float64,2,Array{Float64,2}} with indices -2:2×-2:2:
+OffsetArray{Float64,2,Array{Float64,2}} with indices -2:2×-2:2:
  0.00296902  0.0133062  0.0219382  0.0133062  0.00296902
  0.0133062   0.0596343  0.0983203  0.0596343  0.0133062
  0.0219382   0.0983203  0.162103   0.0983203  0.0219382
@@ -73,7 +73,7 @@ array to one that has coordinates `[0,0,...]` at its center position:
 
 ```julia
 julia> centered([1 0 1; 0 1 0; 1 0 1])
-OffsetArrays.OffsetArray{Int64,2,Array{Int64,2}} with indices -1:1×-1:1:
+OffsetArray{Int64,2,Array{Int64,2}} with indices -1:1×-1:1:
  1  0  1
  0  1  0
  1  0  1
@@ -112,16 +112,16 @@ tuple-of-vectors:
 
 ```julia
 julia> kern1 = centered([1/3, 1/3, 1/3])
-OffsetArrays.OffsetArray{Float64,1,Array{Float64,1}} with indices -1:1:
+OffsetArray{Float64,1,Array{Float64,1}} with indices -1:1:
  0.333333
  0.333333
  0.333333
 
 julia> kernf = kernelfactors((kern1, kern1))
-(ImageFiltering.KernelFactors.ReshapedOneD{Float64,2,0,OffsetArrays.OffsetArray{Float64,1,Array{Float64,1}}}([0.333333,0.333333,0.333333]),ImageFiltering.KernelFactors.ReshapedOneD{Float64,2,1,OffsetArrays.OffsetArray{Float64,1,Array{Float64,1}}}([0.333333,0.333333,0.333333]))
+(ImageFiltering.KernelFactors.ReshapedOneD{Float64,2,0,OffsetArray{Float64,1,Array{Float64,1}}}([0.333333,0.333333,0.333333]),ImageFiltering.KernelFactors.ReshapedOneD{Float64,2,1,OffsetArray{Float64,1,Array{Float64,1}}}([0.333333,0.333333,0.333333]))
 
 julia> kernp = broadcast(*, kernf...)
-OffsetArrays.OffsetArray{Float64,2,Array{Float64,2}} with indices -1:1×-1:1:
+OffsetArray{Float64,2,Array{Float64,2}} with indices -1:1×-1:1:
  0.111111  0.111111  0.111111
  0.111111  0.111111  0.111111
  0.111111  0.111111  0.111111
diff --git a/src/borderarray.jl b/src/borderarray.jl
@@ -26,7 +26,9 @@ end
 """
     BorderArray(inner::AbstractArray, border::AbstractBorder) <: AbstractArray
 
-Construct a thin wrapper around the array `inner`, with given `border`. No data is copied in the constructor, instead border values are computed on the fly in `getindex` calls. Useful for stencil computations. See also [padarray](@ref).
+Construct a thin wrapper around the array `inner`, with given `border`. No data is copied in
+the constructor, instead border values are computed on the fly in `getindex` calls. Useful
+for stencil computations. See also [`padarray`](@ref).
 
 # Examples
 ```julia
diff --git a/src/extrema.jl b/src/extrema.jl
@@ -45,15 +45,15 @@ as a fraction of `maximum(abs, img)` and the volume of the Gaussian.
 While most images are 2- or 3-dimensional, it will be easier to illustrate this with
 a one-dimensional "image" containing two Gaussian blobs of different sizes:
 
-```jldoctest; setup=:(using ImageFiltering), filter=r"amplitude=.*"]
+```jldoctest; setup=:(using ImageFiltering), filter=r"amplitude=.*"
 julia> σs = 2.0.^(1:6);
 
 julia> img = zeros(100); img[20:30] = [exp(-x^2/(2*4^2)) for x=-5:5]; img[50:80] = [exp(-x^2/(2*8^2)) for x=-15:15];
 
 julia> blob_LoG(img, σs; edges=false)
 2-element Vector{BlobLoG{Float64, Tuple{Float64}, 1}}:
- location=CartesianIndex(25,), σ=(4.0,), amplitude=0.10453155018303673
- location=CartesianIndex(65,), σ=(8.0,), amplitude=0.046175719034527364
+ BlobLoG(location=CartesianIndex(25,), σ=(4.0,), amplitude=0.10453155018303673)
+ BlobLoG(location=CartesianIndex(65,), σ=(8.0,), amplitude=0.046175719034527364)
 ```
 
 The other two are centered in their corresponding "features," and the width `σ`
diff --git a/src/imfilter.jl b/src/imfilter.jl
@@ -567,7 +567,7 @@ imfilter(f,w,Inner())
 # References
 1. R. C. Gonzalez and R. E. Woods. *Digital Image Processing (3rd Edition)*.  Upper Saddle River, NJ, USA: Prentice-Hall,  2006.
 
-See also: [`imfilter!`](@ref), [`centered`](@ref), [`padarray`](@ref), [`Pad`](@ref), [`Fill`](@ref), [`Inner`](@ref), [`KernelFactors.IIRGaussian`](@ref).
+See also: [`imfilter!`](@ref), [`centered`](@ref OffsetArrays.centered), [`padarray`](@ref), [`Pad`](@ref), [`Fill`](@ref), [`Inner`](@ref), [`KernelFactors.IIRGaussian`](@ref).
 """
 imfilter
 
diff --git a/src/kernel.jl b/src/kernel.jl
@@ -397,7 +397,7 @@ relative to the corners.
 
 # Examples
 
-```jldoctest
+```jldoctest; setup=:(using ImageFiltering)
 julia> Kernel.laplacian2d(0)      # the standard Laplacian
 3×3 OffsetArray(::Matrix{Float64}, -1:1, -1:1) with eltype Float64 with indices -1:1×-1:1:
  0.0   1.0  0.0
diff --git a/src/mapwindow.jl b/src/mapwindow.jl
@@ -96,7 +96,7 @@ end
 """
     mapwindow!(f, out, img, window; border="replicate", indices=axes(img))
 
-Variant of [mapwindow](@ref), with preallocated output.
+Variant of [`mapwindow`](@ref), with preallocated output.
 If `out` and `img` have overlapping memory regions, behaviour is undefined.
 """
 function mapwindow!(f, out, img, window; border="replicate",
diff --git a/src/models.jl b/src/models.jl
@@ -72,7 +72,7 @@ Mathematically, this function solves the following ROF model using the primal-du
 # References
 
 - [1] Chambolle, A. (2004). "An algorithm for total variation minimization and applications". _Journal of Mathematical Imaging and Vision_. 20: 89–97
-- [2] https://en.wikipedia.org/wiki/Total_variation_denoising
+- [2] [Wikipedia: Total Variation Denoising](https://en.wikipedia.org/wiki/Total_variation_denoising)
 """
 solve_ROF_PD(img::AbstractArray{T}, args...) where T = solve_ROF_PD(float32(T), img, args...)
 function solve_ROF_PD(::Type{T}, img::AbstractArray, args...) where T
diff --git a/src/utils.jl b/src/utils.jl
@@ -13,7 +13,7 @@ and the first dimension size will be approximately half of `sz[1]`.
 `kern` should be zero-centered, i.e.,
 `kern[0, 0]` should reference the center of your kernel,
 and `sz` must be large enough to support `kern`.
-See [`centered`](@ref).
+See [`centered`](@ref OffsetArrays.centered).
 Optionally specify the numeric type `T`
 (which must be one of the types supported by FFTW,
 either `Float32` or `Float64`).
diff --git a/test/runtests.jl b/test/runtests.jl
@@ -1,19 +1,29 @@
 using ImageFiltering, ImageCore, ImageBase
 using OffsetArrays
-using Test
+using Test, Documenter
 using TestImages
 using ImageQualityIndexes
 import StaticArrays
 using Random
 
-# Ambiguity test
-if Base.VERSION >= v"1.6.0-DEV.1005"   # julia #37616
-    @test isempty(detect_ambiguities(ImageFiltering, Kernel, KernelFactors))
-else
-    # Because StaticArrays may have ambiguities with Base, we have to "subtract" these
-    aif = detect_ambiguities(ImageFiltering, Kernel, KernelFactors, Base)
-    asa = detect_ambiguities(StaticArrays, Base)
-    @test isempty(setdiff(aif, asa))
+@testset "Project meta quality checks" begin
+    # Ambiguity test
+    if Base.VERSION >= v"1.6.0-DEV.1005"   # julia #37616
+        @test isempty(detect_ambiguities(ImageFiltering, Kernel, KernelFactors))
+    else
+        # Because StaticArrays may have ambiguities with Base, we have to "subtract" these
+        aif = detect_ambiguities(ImageFiltering, Kernel, KernelFactors, Base)
+        asa = detect_ambiguities(StaticArrays, Base)
+        @test isempty(setdiff(aif, asa))
+    end
+
+    if VERSION >= v"1.3"
+        # TODO(johnnychen94): remove this when upstream ecosystem is ready
+        # https://github.com/JuliaLang/julia/issues/42087
+        if VERSION < v"1.8.0-DEV.840"
+            doctest(ImageFiltering, manual = false)
+        end
+    end
 end
 
 function typestring(::Type{T}) where T   # from https://github.com/JuliaImages/ImageCore.jl/pull/133
