Merge pull request #526 from wheeheee/up_doc

Bump Documenter.jl to v1, fix typos

README.md

@@ -4,7 +4,7 @@ DSP.jl
 [![CI](https://github.com/JuliaDSP/DSP.jl/actions/workflows/CI.yml/badge.svg)](https://github.com/JuliaDSP/DSP.jl/actions?query=workflow%3ACI+branch%3Amaster)
 [![Codecov](http://codecov.io/github/JuliaDSP/DSP.jl/coverage.svg?branch=master)](http://codecov.io/github/JuliaDSP/DSP.jl?branch=master)
 [![Documentation (stable)](https://img.shields.io/badge/docs-stable-blue.svg)](https://docs.juliadsp.org/stable/contents/)
-[![Documentation (latest)](https://img.shields.io/badge/docs-dev-blue.svg)](https://docs.juliadsp.org/latest/contents/)
+[![Documentation (latest)](https://img.shields.io/badge/docs-dev-blue.svg)](https://docs.juliadsp.org/latest/)
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.8344531.svg)](https://doi.org/10.5281/zenodo.8344531)
 
 DSP.jl provides a number of common [digital signal processing](https://en.wikipedia.org/wiki/Digital_signal_processing) routines in Julia. These include:

docs/Project.toml

@@ -3,4 +3,4 @@ DSP = "717857b8-e6f2-59f4-9121-6e50c889abd2"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 
 [compat]
-Documenter = "0.26"
+Documenter = "1"

docs/make.jl

@@ -6,16 +6,19 @@ makedocs(
     modules = [DSP],
     format = Documenter.HTML(),
     sitename = "DSP.jl",
-    pages = Any[
-        "Contents" => "contents.md",
-        "periodograms.md",
-        "estimation.md",
-        "windows.md",
-        "filters.md",
-        "util.md",
-        "convolutions.md",
-        "lpc.md",
-        "index.md",
+    pages = [
+        "Home" => "index.md",
+        "Submodules" => [
+            "periodograms.md",
+            "estimation.md",
+            "windows.md",
+            "filters.md",
+            "util.md",
+            "convolutions.md",
+            "lpc.md"
+        ],
+        "Internals" => "internals.md",
+        "Index" => "appendix.md"
     ],
 )
 

docs/src/appendix.md

@@ -0,0 +1,4 @@
+# Index
+
+```@index
+```

docs/src/filters.md

@@ -23,23 +23,23 @@ SecondOrderSections
 
 These filter coefficient objects support the following arithmetic operations:
 inversion (`inv`), multiplication (`*`) for series connection, and integral
-power (`^`) for repeated mutlpilcation with itself. For example:
+power (`^`) for repeated multiplication with itself. For example:
 
 ```jldoctest; setup = :(using DSP)
 julia> H = PolynomialRatio([1.0], [1.0, 0.3])
-PolynomialRatio{:z, Float64}(Polynomials.LaurentPolynomial(1.0), Polynomials.LaurentPolynomial(0.3*z⁻¹ + 1.0))
+PolynomialRatio{:z, Float64}(LaurentPolynomial(1.0), LaurentPolynomial(0.3*z⁻¹ + 1.0))
 
 julia> inv(H)
-PolynomialRatio{:z, Float64}(Polynomials.LaurentPolynomial(0.3*z⁻¹ + 1.0), Polynomials.LaurentPolynomial(1.0))
+PolynomialRatio{:z, Float64}(LaurentPolynomial(0.3*z⁻¹ + 1.0), LaurentPolynomial(1.0))
 
 julia> H * H
-PolynomialRatio{:z, Float64}(Polynomials.LaurentPolynomial(1.0), Polynomials.LaurentPolynomial(0.09*z⁻² + 0.6*z⁻¹ + 1.0))
+PolynomialRatio{:z, Float64}(LaurentPolynomial(1.0), LaurentPolynomial(0.09*z⁻² + 0.6*z⁻¹ + 1.0))
 
 julia> H^2
-PolynomialRatio{:z, Float64}(Polynomials.LaurentPolynomial(1.0), Polynomials.LaurentPolynomial(0.09*z⁻² + 0.6*z⁻¹ + 1.0))
+PolynomialRatio{:z, Float64}(LaurentPolynomial(1.0), LaurentPolynomial(0.09*z⁻² + 0.6*z⁻¹ + 1.0))
 
 julia> H^-2
-PolynomialRatio{:z, Float64}(Polynomials.LaurentPolynomial(0.09*z⁻² + 0.6*z⁻¹ + 1.0), Polynomials.LaurentPolynomial(1.0))
+PolynomialRatio{:z, Float64}(LaurentPolynomial(0.09*z⁻² + 0.6*z⁻¹ + 1.0), LaurentPolynomial(1.0))
 
 ```
 
@@ -79,26 +79,30 @@ Most analog and digital filters are constructed by composing
 [response types](@ref response-types), which determine the frequency
 response of the filter, with [design methods](@ref design-methods),
 which determine how the filter is constructed.
+
 The response type is [`Lowpass`](@ref), [`Highpass`](@ref), [`Bandpass`](@ref)
 or [`Bandstop`](@ref) and includes the edges of the bands.
-The design method is [`Butterworth`](@ref), [`Chebyshev1`](@ref), [`Chebyshev2`](@ref), 
+
+The design method is [`Butterworth`](@ref), [`Chebyshev1`](@ref), [`Chebyshev2`](@ref),
 [`Elliptic`](@ref), or [`FIRWindow`](@ref), and includes any
 necessary parameters for the method that affect the shape of the response,
-such as filter order, ripple, and attenuation. [Filter order estimation methods](@ref order-est-methods) 
-are available in [`buttord`](@ref), [`cheb1ord`](@ref), [`cheb2ord`](@ref), 
-and [`ellipord`](@ref) if the corner frequencies for different IIR filter types are known. [`remezord`](@ref) 
-can be used for an initial FIR filter order estimate.
+such as filter order, ripple, and attenuation.
+
+[Filter order estimation methods](@ref order-est-methods)
+are available in [`buttord`](@ref), [`cheb1ord`](@ref), [`cheb2ord`](@ref),
+and [`ellipord`](@ref) if the corner frequencies for different IIR filter types are known.
+[`remezord`](@ref) can be used for an initial FIR filter order estimate.
 
 ```@docs
 analogfilter
 digitalfilter
 ```
 
-For some filters, the design method is more general or 
+For some filters, the design method is more general or
 inherently implies a response type;
 these [direct design methods](@ref direct-design-methods)
 include [`remez`](@ref) which designs equiripple FIR
-filters of all types, and [`iirnotch`](@ref) which designs a 
+filters of all types, and [`iirnotch`](@ref) which designs a
 2nd order "biquad" IIR notch filter.
 
 

docs/src/index.md

@@ -1,4 +1,18 @@
-# Index
+# Welcome to DSP.jl's documentation!
 
-```@index
+DSP.jl provides a number of common [digital signal processing](https://en.wikipedia.org/wiki/Digital_signal_processing) routines in Julia. So far, the following submodules are implemented:
+
+## Table of contents
+```@contents
+Pages = [
+    "periodograms.md",
+    "estimation.md",
+    "windows.md",
+    "filters.md",
+    "util.md",
+    "convolutions.md",
+    "lpc.md",
+    "internals.md",
+    "index.md",
+]
 ```

docs/src/internals.md

@@ -0,0 +1,19 @@
+# Internals
+Functions here are not exported.
+
+```@docs
+DSP.os_fft_complexity
+DSP.os_prepare_conv
+DSP.os_conv_block!
+DSP.os_filter_transform!
+DSP.Windows.makewindow
+DSP.Windows.padplot
+DSP._zeropad
+DSP._zeropad!
+DSP._zeropad_keep_offset
+DSP.Filters.freq_eval
+DSP.Filters.build_grid
+DSP.Filters.lagrange_interp
+DSP.Periodograms.coherence_from_cs!
+DSP.optimalfftfiltlength
+```

docs/src/periodograms.md

@@ -1,5 +1,9 @@
 # `Periodograms` - periodogram estimation
 
+## Basic functions
+Common procedures like computing the [short-time Fourier transform](@ref stft),
+[`periodogram`](@ref)s, and [`spectrogram`](@ref)s are documented below.
+
 ```@docs
 arraysplit
 periodogram(s::AbstractVector{T}) where T <: Number
@@ -11,6 +15,7 @@ freq
 power
 time
 coherence
+DSP.Periodograms.Coherence
 ```
 
 ## Multitaper periodogram estimation
@@ -22,11 +27,12 @@ mt_spectrogram
 mt_spectrogram!
 mt_cross_power_spectra
 mt_cross_power_spectra!
+DSP.Periodograms.CrossPowerSpectra
 mt_coherence
 mt_coherence!
 ```
 
-### Configuration objects
+## Configuration objects
 
 ```@docs
 MTConfig

src/DSP.jl

@@ -6,7 +6,7 @@ using IterTools: subsets
 
 export conv, deconv, filt, filt!, xcorr
 
-# This function has methods added in `peridograms` but is not exported,
+# This function has methods added in `periodograms` but is not exported,
 # so we define it here so one can do `DSP.allocate_output` instead of
 # `DSP.Periodograms.allocate_output`.
 function allocate_output end

src/Filters/design.jl

@@ -468,11 +468,12 @@ digitalfilter(ftype::FilterType, proto::FilterCoefficients) =
 """
     iirnotch(Wn, bandwidth[; fs])
 
-Second-order digital IIR notch filter [^Orfandis] at frequency `Wn` with
+Second-order digital IIR notch filter [^Orfanidis] at frequency `Wn` with
 bandwidth `bandwidth`. If `fs` is not specified, `Wn` is
 interpreted as a normalized frequency in half-cycles/sample.
 
-[^Orfandis]: Orfanidis, S. J. (1996). Introduction to signal processing. Englewood Cliffs, N.J: Prentice Hall, p. 370.
+[^Orfanidis]: Orfanidis, S. J. (1996). Introduction to signal processing.
+    Englewood Cliffs, N.J: Prentice Hall, p. 370.
 """
 function iirnotch(w::Real, bandwidth::Real; fs=2)
     w = normalize_freq(w, fs)

src/Filters/filt_order.jl

@@ -42,16 +42,16 @@ THE POSSIBILITY OF SUCH DAMAGE.
 Design equations based on [1], Chapter 10. Brent's method with Parabolic interpolation
 uses code from [3], modifications from Optim.jl's Brent method in [4].
 
-[1] Proakis, J. G., & Manolakis, D. G. (1996). Digital Signal Processing, Fourth Edition. 
+[1] Proakis, J. G., & Manolakis, D. G. (1996). Digital Signal Processing, Fourth Edition.
 Prentice Hall, New Jersey.
 
-[2] Virtanen, P., Gommers, R., Oliphant, T. E., Haberland, M., Reddy, T., 
-Cournapeau, D., ... & Van Mulbregt, P. (2020). SciPy 1.0: fundamental algorithms for scientific 
+[2] Virtanen, P., Gommers, R., Oliphant, T. E., Haberland, M., Reddy, T.,
+Cournapeau, D., ... & Van Mulbregt, P. (2020). SciPy 1.0: fundamental algorithms for scientific
 computing in Python. Nature methods, 17(3), 261-272.
 
 [3] W. H. Press, et al. Numerical recipes. Third Edition. Cambridge university press, 2007. Chapter 10.3
 
-[4] P. K. Mogensen and A. N. Riseth, Optim: A mathematical optimization package for Julia. Journal of Open 
+[4] P. K. Mogensen and A. N. Riseth, Optim: A mathematical optimization package for Julia. Journal of Open
 Source Software, 2018. https://github.com/JuliaNLSolvers/Optim.jl/blob/master/src/univariate/solvers/brent.jl
 
 ====================================================================#
@@ -226,12 +226,12 @@ end
 """
     (N, ωn) = buttord(Wp::Tuple{Real,Real}, Ws::Tuple{Real,Real}, Rp::Real, Rs::Real; domain=:z)
 
-Butterworth order estimate for bandpass and bandstop filter types.  `Wp` and `Ws` are 2-element pass 
-and stopband frequency edges, with no more than `Rp` dB passband ripple and at least `Rs` dB stopband 
-attenuation. Based on the ordering of passband and bandstop edges,  the Bandstop or Bandpass filter 
+Butterworth order estimate for bandpass and bandstop filter types.  `Wp` and `Ws` are 2-element pass
+and stopband frequency edges, with no more than `Rp` dB passband ripple and at least `Rs` dB stopband
+attenuation. Based on the ordering of passband and bandstop edges,  the Bandstop or Bandpass filter
 type is inferred. `N` is an integer indicating the lowest estimated filter order, with `ωn` specifying
-the cutoff or "-3 dB" frequencies. If a domain of `:s` is specified, the passband and stopband frequencies 
-are interpretted as radians/second, giving an order and natural frequencies for an analog filter. The default
+the cutoff or "-3 dB" frequencies. If a domain of `:s` is specified, the passband and stopband frequencies
+are interpreted as radians/second, giving an order and natural frequencies for an analog filter. The default
 domain is `:z`, interpretting the input frequencies as normalized from 0 to 1, where 1 corresponds to π radians/sample.
 """
 function buttord(Wp::Tuple{Real,Real}, Ws::Tuple{Real,Real}, Rp::Real, Rs::Real; domain::Symbol=:z)
@@ -277,14 +277,14 @@ end
 """
     (N, ωn) = buttord(Wp::Real, Ws::Real, Rp::Real, Rs::Real; domain=:z)
 
-LPF/HPF Butterworth filter order and -3 dB frequency approximation. `Wp` and `Ws` are 
-the passband and stopband frequencies, whereas Rp and Rs  are the passband and stopband 
-ripple attenuations in dB. If the passband is greater than stopband, the filter type 
+LPF/HPF Butterworth filter order and -3 dB frequency approximation. `Wp` and `Ws` are
+the passband and stopband frequencies, whereas Rp and Rs  are the passband and stopband
+ripple attenuations in dB. If the passband is greater than stopband, the filter type
 is inferred to be for estimating the order of a highpass filter. `N` specifies the lowest
-possible integer filter order, whereas `ωn` is the cutoff or "-3 dB" frequency. If a domain 
-of `:s` is specified, the passband and stopband edges are interpretted as radians/second, 
-giving an order and natural frequency result for an analog filter. The default domain 
-is `:z`, interpretting the input frequencies as normalized from 0 to 1, where 1 corresponds 
+possible integer filter order, whereas `ωn` is the cutoff or "-3 dB" frequency. If a domain
+of `:s` is specified, the passband and stopband edges are interpreted as radians/second,
+giving an order and natural frequency result for an analog filter. The default domain
+is `:z`, interpretting the input frequencies as normalized from 0 to 1, where 1 corresponds
 to π radians/sample.
 """
 function buttord(Wp::Real, Ws::Real, Rp::Real, Rs::Real; domain::Symbol=:z)
@@ -302,7 +302,7 @@ function buttord(Wp::Real, Ws::Real, Rp::Real, Rs::Real; domain::Symbol=:z)
     end
     wa = toprototype(Ωp, Ωs, ftype)
 
-    # rounding up fractional order. Using differences of logs instead of division. 
+    # rounding up fractional order. Using differences of logs instead of division.
     N = ceil(Int, butterworth_order_estimate(Rp, Rs, wa))
 
     # specifications for the stopband ripple are met precisely.
@@ -334,7 +334,7 @@ for (fcn, est, filt) in ((:ellipord, :elliptic, "Elliptic (Cauer)"),
         Based on the ordering of passband and stopband edges, the Lowpass or Highpass filter type is inferred.
         `N` indicates the smallest integer filter order that achieves the desired specifications,
         and `ωn` contains the natural frequency of the filter, (in this case, simply the passband edge.)
-        If a domain of `:s` is specified, the passband and stopband edges are interpretted
+        If a domain of `:s` is specified, the passband and stopband edges are interpreted
         as radians/second, giving an order and natural frequency result for an analog filter.
         The default domain is `:z`, interpretting the input frequencies as normalized from 0 to 1,
         where 1 corresponds to π radians/sample.
@@ -364,11 +364,11 @@ for (fcn, est, filt) in ((:ellipord, :elliptic, "Elliptic (Cauer)"),
 
         Integer and natural frequency order estimation for $($filt) Filters. `Wp` and `Ws` are 2-element
         frequency edges for Bandpass/Bandstop cases, with `Rp` and `Rs` representing the ripple maximum loss
-        in the passband and minimum ripple attenuation in the stopband in dB. Based on the ordering of passband 
-        and bandstop edges, the Bandstop or Bandpass filter type is inferred. `N` is an integer indicating the 
-        lowest estimated filter order, with `ωn` specifying the cutoff or "-3 dB" frequencies. If a domain of 
-        `:s` is specified, the passband and stopband frequencies are interpretted as radians/second, giving an 
-        order and natural frequencies for an analog filter. The default domain is `:z`, interpretting the input 
+        in the passband and minimum ripple attenuation in the stopband in dB. Based on the ordering of passband
+        and bandstop edges, the Bandstop or Bandpass filter type is inferred. `N` is an integer indicating the
+        lowest estimated filter order, with `ωn` specifying the cutoff or "-3 dB" frequencies. If a domain of
+        `:s` is specified, the passband and stopband frequencies are interpreted as radians/second, giving an
+        order and natural frequencies for an analog filter. The default domain is `:z`, interpreting the input
         frequencies as normalized from 0 to 1, where 1 corresponds to π radians/sample.
         """
         function $fcn(Wp::Tuple{Real,Real}, Ws::Tuple{Real,Real}, Rp::Real, Rs::Real; domain::Symbol=:z)
@@ -400,7 +400,7 @@ are the frequency edges for Bandpass/Bandstop cases, with `Rp` and `Rs` represen
 loss in the passband and minimum ripple attenuation in the stopband in dB. Based on the ordering of
 the passband and stopband edges, the Lowpass or Highpass filter type is inferred. `N` is the integer
 indicating the lowest filter order, with `ωn` specifying the "-3 dB" cutoff frequency. If the domain
-is specified as `:s`, the passband and stopband frequencies are interpretted as radians/second, giving
+is specified as `:s`, the passband and stopband frequencies are interpreted as radians/second, giving
 the order and natural frequencies for an analog filter. The default domain is `:z`, interpretting the
 input frequencies as normalized from 0 to 1, where 1 corresponds to π radians/sample.
 """
@@ -421,13 +421,13 @@ end
 """
     (N, ωn) = cheb2ord(Wp::Tuple{Real, Real}, Ws::Tuple{Real, Real}, Rp::Real, Rs::Real; domain::Symbol=:z)
 
-Integer and natural frequency order estimation for Chebyshev Type II (inverse) Filters. `Wp` and `Ws` are 
-2-element frequency edges for Bandpass/Bandstop cases, with `Rp` and `Rs` representing  the ripple maximum 
-loss in the passband and minimum ripple attenuation in the stopband in dB. Based on the ordering of passband 
-and bandstop edges, the Bandstop or Bandpass filter type is inferred. `N` is an integer indicating the 
-lowest estimated filter order, with `ωn` specifying the cutoff or "-3 dB" frequencies. If a domain of 
-`:s` is specified, the passband and stopband frequencies are interpretted as radians/second, giving an 
-order and natural frequencies for an analog filter. The default domain is `:z`, interpretting the input 
+Integer and natural frequency order estimation for Chebyshev Type II (inverse) Filters. `Wp` and `Ws` are
+2-element frequency edges for Bandpass/Bandstop cases, with `Rp` and `Rs` representing  the ripple maximum
+loss in the passband and minimum ripple attenuation in the stopband in dB. Based on the ordering of passband
+and bandstop edges, the Bandstop or Bandpass filter type is inferred. `N` is an integer indicating the
+lowest estimated filter order, with `ωn` specifying the cutoff or "-3 dB" frequencies. If a domain of
+`:s` is specified, the passband and stopband frequencies are interpreted as radians/second, giving an
+order and natural frequencies for an analog filter. The default domain is `:z`, interpretting the input
 frequencies as normalized from 0 to 1, where 1 corresponds to π radians/sample.
 """
 function cheb2ord(Wp::Tuple{Real,Real}, Ws::Tuple{Real,Real}, Rp::Real, Rs::Real; domain::Symbol=:z)
@@ -464,17 +464,17 @@ end
 
 Order estimation for lowpass digital filter cases based
 on the equations and coefficients in [^Rabiner]. The original
-equation returned the minimum filterlength, whereas this implementation 
-returns the order (N=L-1). `Wp` and  `Ws` are the normalized passband and 
-stopband frequencies, with `Rp` indicating the passband ripple and `Rs` is the 
-stopband attenuation (linear.) 
+equation returned the minimum filterlength, whereas this implementation
+returns the order (N=L-1). `Wp` and `Ws` are the normalized passband and
+stopband frequencies, with `Rp` indicating the passband ripple and `Rs` is the
+stopband attenuation (linear.)
 
 NOTE: The value of N is an initial approximation. If under-estimated, the order
 should be increased until the design specifications are met.
 
-[^Rabiner]: Herrmann, O., Lawrence R. Rabiner, and D. S. K. Chan. "Practical 
-design rules for optimum finite impulse response lowpass digital filters." Bell System 
-Technical Journal 52.6 (1973): 769-799.
+[^Rabiner]: Herrmann, O., Lawrence R. Rabiner, and D. S. K. Chan.
+    "Practical design rules for optimum finite impulse response lowpass digital filters."
+    Bell System Technical Journal 52.6 (1973): 769-799.
 """
 function remezord(Wp::Real, Ws::Real, Rp::Real, Rs::Real)
     (0 > Wp > 0.5) || (0 > Ws > 0.5) && throw(ArgumentError("Pass and stopband edges must be greater than DC and less than Nyquist."))