Add external links to the documentation and update Documenter compat (#322)

* fix(docs): Update compat bound for Documenter and dev the package

It should keep the package updated when building the docs.

* feat(docs): Add the DocumenterInterLinks package for external documentation links

* feat(docs): Use `@extref` for external references

* fix(docs): Add  `repo` to `make.jl`

* fix(docs): Add `set_provider!` to the documentation

Author: kunzaatko

docs/Project.toml

@@ -1,5 +1,11 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterInterLinks = "d12716ef-a0f6-4df4-a9f1-a5a34e75c656"
+FFTW = "7a1cc6ca-52ef-59f5-83cd-3a7055c09341"
+
+[sources]
+FFTW = { path = ".." }
 
 [compat]
-Documenter = "~0.26"
+Documenter = "^1"
+DocumenterInterLinks = "^1.1"

docs/make.jl

@@ -1,14 +1,21 @@
-using Documenter, FFTW
+using Documenter, DocumenterInterLinks, FFTW
+
+links = InterLinks(
+    "Julia" => "https://docs.julialang.org/en/v1/",
+    "AbstractFFTs" => "https://juliamath.github.io/AbstractFFTs.jl/dev/",
+)
 
 makedocs(
     modules = [FFTW],
     clean = false,
+    repo = Remotes.GitHub("JuliaMath", "FFTW.jl"),
     sitename = "FFTW.jl",
     pages = Any[
         "Home" => "index.md",
         "API" => "fft.md",
         "Examples" => "examples.md",
     ],
+    plugins=[links],
 )
 
 deploydocs(

docs/src/fft.md

@@ -20,4 +20,5 @@ FFTW.plan_dct
 FFTW.plan_idct
 FFTW.plan_dct!
 FFTW.plan_idct!
+FFTW.set_provider!
 ```

docs/src/index.md

@@ -15,12 +15,10 @@ Pkg.add("FFTW")
 
 from the Julia REPL.
 
-Users with a build of Julia based on Intel's Math Kernel Library (MKL) can use MKL
-for FFTs by setting a preference in their top-level project by either using the
-`FFTW.set_provider!()` method, or by directly setting the preference using
-[`Preferences.jl`](https://github.com/JuliaPackaging/Preferences.jl).  Note that this
-choice will be recorded for the current project, and other projects that wish to use
-MKL for FFTs should also set that same preference.
-Note further that MKL provides only a subset of the functionality provided by FFTW. See
-Intel's [documentation](https://software.intel.com/en-us/mkl-developer-reference-c-using-fftw3-wrappers)
-for more information about potential differences or gaps in functionality.
+Users with a build of Julia based on Intel's Math Kernel Library (MKL) can use MKL for FFTs by setting a preference in
+their top-level project by either using the [`FFTW.set_provider!()`](@ref) method, or by directly setting the preference
+using [`Preferences.jl`](https://github.com/JuliaPackaging/Preferences.jl).  Note that this choice will be recorded for
+the current project, and other projects that wish to use MKL for FFTs should also set that same preference. Note further
+that MKL provides only a subset of the functionality provided by FFTW. See Intel's
+[documentation](https://software.intel.com/en-us/mkl-developer-reference-c-using-fftw3-wrappers) for more information
+about potential differences or gaps in functionality.

src/dct.jl

@@ -12,20 +12,17 @@ function plan_dct! end
 """
     plan_idct(A [, dims [, flags [, timelimit [, num_threads]]]])
 
-Pre-plan an optimized inverse discrete cosine transform (DCT), similar to
-[`plan_fft`](@ref) except producing a function that computes
-[`idct`](@ref). The first two arguments have the same meaning as for
+Pre-plan an optimized inverse discrete cosine transform (DCT), similar to [`plan_fft`](@extref `AbstractFFTs.plan_fft`)
+except producing a function that computes [`idct`](@ref). The first two arguments have the same meaning as for
 [`idct`](@ref).
 """
 function plan_idct end
 
 """
     plan_dct(A [, dims [, flags [, timelimit [, num_threads]]]])
 
-Pre-plan an optimized discrete cosine transform (DCT), similar to
-[`plan_fft`](@ref) except producing a function that computes
-[`dct`](@ref). The first two arguments have the same meaning as for
-[`dct`](@ref).
+Pre-plan an optimized discrete cosine transform (DCT), similar to [`plan_fft`](@extref `AbstractFFTs.plan_fft`) except
+producing a function that computes [`dct`](@ref). The first two arguments have the same meaning as for [`dct`](@ref).
 """
 function plan_dct end
 
@@ -39,12 +36,10 @@ function plan_idct! end
 """
     dct(A [, dims])
 
-Performs a multidimensional type-II discrete cosine transform (DCT) of the array `A`, using
-the unitary normalization of the DCT. The optional `dims` argument specifies an iterable
-subset of dimensions (e.g. an integer, range, tuple, or array) to transform along.  Most
-efficient if the size of `A` along the transformed dimensions is a product of small primes;
-see [`nextprod`](@ref). See also [`plan_dct`](@ref) for even greater
-efficiency.
+Performs a multidimensional type-II discrete cosine transform (DCT) of the array `A`, using the unitary normalization of
+the DCT. The optional `dims` argument specifies an iterable subset of dimensions (e.g. an integer, range, tuple, or
+array) to transform along.  Most efficient if the size of `A` along the transformed dimensions is a product of small
+primes; see [`nextprod`](@extref `Base.nextprod`). See also [`plan_dct`](@ref) for even greater efficiency.
 """
 function dct end
 
@@ -55,7 +50,7 @@ Computes the multidimensional inverse discrete cosine transform (DCT) of the arr
 (technically, a type-III DCT with the unitary normalization). The optional `dims` argument
 specifies an iterable subset of dimensions (e.g. an integer, range, tuple, or array) to
 transform along.  Most efficient if the size of `A` along the transformed dimensions is a
-product of small primes; see [`nextprod`](@ref).  See also
+product of small primes; see [`nextprod`](@extref `Base.nextprod`).  See also
 [`plan_idct`](@ref) for even greater efficiency.
 """
 function idct end

src/fft.jl

@@ -40,16 +40,15 @@ function r2r! end
 """
     plan_r2r!(A, kind [, dims [, flags [, timelimit [, num_threads]]]])
 
-Similar to [`plan_fft`](@ref), but corresponds to [`r2r!`](@ref).
+Similar to [`plan_fft`](@extref `AbstractFFTs.plan_fft`), but corresponds to [`r2r!`](@ref).
 """
 function plan_r2r! end
 
 """
     plan_r2r(A, kind [, dims [, flags [, timelimit [, num_threads]]]])
 
-Pre-plan an optimized r2r transform, similar to [`plan_fft`](@ref)
-except that the transforms (and the first three arguments)
-correspond to [`r2r`](@ref) and [`r2r!`](@ref), respectively.
+Pre-plan an optimized r2r transform, similar to [`plan_fft`](@extref `AbstractFFTs.plan_fft`) except that the
+transforms (and the first three arguments) correspond to [`r2r`](@ref) and [`r2r!`](@ref), respectively.
 """
 function plan_r2r end