Documenter 1 (#399)

* bump documenter version

* documentation fixes for issues exposed bumping Documenter to v1.0

Author: jverzani

docs/Project.toml

@@ -13,3 +13,7 @@ Roots = "f2b01f46-fcfa-551c-844a-d8ac1e96c665"
 SymPy = "24249f21-da20-56a4-8eb1-6a02cf4ae2e6"
 UnicodePlots = "b8865327-cd53-5732-bb35-84acbb429228"
 Unitful = "1986cc42-f94f-5a68-af5c-568840ba703d"
+
+
+[compat]
+Documenter = "1"

docs/src/geometry-zero-finding.md

@@ -4,10 +4,11 @@ We illustrate the geometry behind a single step of several different, non-bracke
 
 ## Newton's method
 
-We load the `Plots`, `ForwardDiff`, and `Roots` packages:
+In addition to `Roots`, we use the `Plots` and `ForwardDiff` packages:
 
 ```@example geometry
-using Plots, ForwardDiff,  Roots
+using Roots
+using Plots, ForwardDiff
 Base.adjoint(f::Function)  = x  -> ForwardDiff.derivative(f, float(x)) # f' will compute derivative
 ```
 
@@ -82,8 +83,10 @@ plot!(sl, color=:red, linewidth=3)
 scatter!([x0, x1, x2], [0,0,0]; markercolor=:blue)
 annotate!([(x0,0,"x0", :bottom), (x1, 0, "x1", :bottom), (x2,0,"x2", :bottom)])
 scatter!([x0, x1], [f(x0), f(x1)]; markercolor=:blue)
+
 scatter!([α],[0]; markercolor=:blue)
 annotate!([(α, 0, "α", :top)])
+
 p
 ```
 
@@ -192,6 +195,7 @@ scatter!(xs, zero.(xs);  markercolor=:blue)
 
 scatter!([α],[0]; markercolor=:blue)
 annotate!([(α, 0, "α", :top)])
+
 p
 ```
 
@@ -218,8 +222,10 @@ for (i,x) ∈ enumerate(xs)
 end
 annotate!([(x4, 0, "x4", :bottom)])
 scatter!(xs, f.(xs); markercolor=:blue)
+
 scatter!([α],[0]; markercolor=:blue)
 annotate!([(α, 0, "α", :top)])
+
 p
 ```
 
@@ -266,16 +272,18 @@ x0 = 1.4
 x1 = x0 - 2 / (1 + sqrt(1 - 2L_f(x0))) * f(x0)/f'(x0)
 t2(x) = f(x0) + f'(x0)*(x-x0) + f''(x0)/2 * (x - x0)^2
 
-
-p = plot(f, 1.1, 1.5; legend=false, linewidth=3)
+a, b = 1.1, 1.5
+p = plot(f, a, b; legend=false, linewidth=3)
 plot!(zero)
 plot!(t2; color=:red, linewidth=3)
 
 scatter!([x0, x1], [0,0]; markercolor=:blue)
 annotate!([(x0,0,"x0", :bottom), (x1, 0, "x1", :bottom)])
 scatter!([x0], [f(x0)]; markercolor=:blue)
+
 scatter!([α],[0]; markercolor=:blue)
 annotate!([(α, 0, "α", :top)])
+
 p
 ```
 
@@ -300,11 +308,11 @@ We can visualize, as follows, using a contour plot to represent the hyperbola.
 x1 = x0 - 2 / (2 - L_f(x0)) * f(x0)/f'(x0)
 F(x,y) = y - f(x0) - f'(x0)*(x-x0) - f''(x0)/(2f'(x0)) * (x-x0) * (y-f(x0))
 
-
-plot(f, 1.1, 1.5; legend=false, linewidth=3)
+a, b = 1.1, 1.5
+p = plot(f, a, b; legend=false, linewidth=3)
 plot!(zero)
-xs′, ys′ = range(1.1, 1.5, length=50), range(f(1.1), f(1.5), length=50);
-zs = [F(x,y) for y ∈ ys′, x ∈ xs′];
+xs, ys = range(a, b, length=50), range(f(a), f(b), length=50);
+zs = [F(x,y) for y ∈ ys, x ∈ xs];
 contour!(xs, ys, zs; levels = [0], color=:red, linewidth=3)
 
 scatter!([x0, x1], [0,0]; markercolor=:blue)
@@ -314,6 +322,7 @@ scatter!([x0], [f(x0)]; markercolor=:blue)
 
 scatter!([α],[0]; markercolor=:blue)
 annotate!([(α, 0, "α", :top)])
+
 p
 ```
 
@@ -336,13 +345,14 @@ x_{n+1} = x_n - (1 + \frac{1}{2} L_f(x_n)) \frac{f(x_n)}{f'(x_n)}.
 This is visualized in a similar manner as the last example:
 
 ```@example geometry
-x1 = x0 + (1 - 1/2 * L_f(x0)) * f(x0) / f'(x0)
+x1 = x0 - (1 + 1/2 * L_f(x0)) * f(x0) / f'(x0)
 F(x, y) = -f''(x0)/(2f'(x0)^2) * (y-f(x0))^2 + y - f(x0)  - f'(x0) * (x- x0)
 
-plot(f, 1.1, 1.5; legend=false, linewidth=3)
+a, b = 1.1, 1.5
+p = plot(f, a, b; legend=false, linewidth=3)
 plot!(zero)
-xs′, ys′ = range(1.1, 1.5, length=50), range(f(1.1), f(1.5), length=50);
-zs = [F(x,y) for y ∈ ys′, x ∈ xs′];
+xs, ys = range(a, b, length=50), range(f(a), f(b), length=50);
+zs = [F(x,y) for y ∈ ys, x ∈ xs];
 contour!(xs, ys, zs; levels = [0], color=:red, linewidth=3)
 
 scatter!([x0, x1], [0,0]; markermarkercolor=:blue)
@@ -352,6 +362,7 @@ scatter!([x0], [f(x0)]; markermarkercolor=:blue)
 
 scatter!([α],[0]; markermarkercolor=:blue)
 annotate!([(α, 0, "α", :top)])
+
 p
 ```
 
@@ -384,23 +395,27 @@ Newton's method is recovered by letting ``b_n \rightarrow 0``, Chebyshev's metho
 The super-Halley method is when ``b_n = -f''(x_n)/f'(x_n)``. We can visualize this:
 
 ```@example geometry
-cn = -f(x0)
+cn = -f'(x0)
 bn = -f''(x0)/f'(x0)
-an = -f''(x0)/(2f'(x0)) - bn/f'(x0)
-x1 = x0 - (1 + 1/2 * (L_f(x0) / (1 + bn * (f(x0)/f'(x0))))) * f(x0)/f'(x0)
+an = -f''(x0)/(2f'(x0)^2) - bn/f'(x0)
+x1 = x0 - (1 + 1/2 * (L_f(x0) / (1 + bn * f(x0) / f'(x0)))) * f(x0)/f'(x0)
 F(x, y) = x - x0 + (y-f(x0)) * (1 + an * (y - f(x0))) / (bn * (y - f(x0)) + cn)
 
-plot(f, 1.1, 1.5; legend=false, linewidth=3)
+
+a, b= 1.1, 1.5
+p = plot(f, a, b; legend=false, linewidth=3)
 plot!(zero)
-xs′, ys′ = range(1.1, 1.5, length=50), range(f(1.1), f(1.5), length=50);
-zs = [F(x,y) for y ∈ ys′, x ∈ xs′];
+xs, ys = range(a, b, length=50), range(f(a), f(b), length=50);
+zs = [F(x,y) for y ∈ ys, x ∈ xs];
 contour!(xs, ys, zs; levels = [0], color=:red, linewidth=3)
 
 scatter!([x0, x1], [0,0]; markercolor=:blue)
 annotate!([(x0,0,"x0", :bottom), (x1, 0, "x1", :bottom)])
 scatter!([x0], [f(x0)]; markercolor=:blue)
+
 scatter!([α],[0]; markercolor=:blue)
 annotate!([(α, 0, "α", :top)])
+
 p
 ```
 

docs/src/index.md

@@ -12,7 +12,7 @@ The `find_zero` function provides the
 primary interface. It supports various algorithms through the
 specification of a method. These include:
 
-* Bisection-like algorithms. For functions where a bracketing interval
+* Bisection-like methods. For functions where a bracketing interval
   is known (one where ``f(a)`` and ``f(b)`` have alternate signs),
   there are several bracketing methods, including `Bisection`.  For
   most floating point number types, bisection occurs in a manner
@@ -27,7 +27,7 @@ specification of a method. These include:
   iterations and are more performant.
 
 
-* Several derivative-free methods are implemented. These are specified
+* Several derivative-free methods. These are specified
   through the methods `Order0`, `Order1` (the secant method), `Order2`
   (the Steffensen method), `Order5`, `Order8`, and `Order16`. The
   number indicates, roughly, the order of convergence. The `Order0`
@@ -40,7 +40,7 @@ specification of a method. These include:
   multiplicity of the zero.
 
 
-* There are methods that require a derivative or two: `Roots.Newton`,
+* Methods requiring one or more derivatives: `Roots.Newton`,
   `Roots.Halley` are classical ones, `Roots.QuadraticInverse`,
   `Roots.ChebyshevLike`, `Roots.SuperHalley` are others.
   `Roots.Schroder` provides a quadratic method, like Newton's method,
@@ -78,7 +78,7 @@ true
 
 The default algorithm is guaranteed to have an  answer nearly as accurate as is  possible  given the limitations of floating point  computations.
 
-For the zeros "near" a point,  a non-bracketing method is often used, as generally  the algorithms are more efficient and can be  used in cases where a zero does  not cross the ``x`` axis. Passing just  the initial point will dispatch to  such a method:
+For the zeros "near" a point,  a non-bracketing method is often used, as generally  the algorithms are more efficient and can be  used in cases where a zero does  not cross the ``x`` axis. Passing just an initial guess will dispatch to such a method:
 
 ```jldoctest find_zero
 julia> find_zero(f,  0.6) ≈ 0.550606579334135

docs/src/reference.md

@@ -21,6 +21,10 @@ end
 CurrentModule = Roots
 ```
 
+```@docs
+Roots
+```
+
 ##  The `find_zero`  and `find_zeros` functions
 
 There are  two main  functions:  `find_zero`   to  identify  a  zero  of  ``f``  given  some initial starting  value or  bracketing interval and  `find_zeros` to heuristically identify  all  zeros in  a specified interval.
@@ -37,6 +41,7 @@ The problem-algorithm-solve interface is a pattern popularized in `Julia` by the
 
 ```@docs
 Roots.solve!
+Roots.solve
 Roots.ZeroProblem
 ```
 
@@ -108,7 +113,9 @@ only requires one new  function call per  step  so  can be very effective. Often
 
 ```@docs
 Secant
+Order1
 Steffensen
+Order2
 Order5
 Order8
 Order16
@@ -148,7 +155,9 @@ Derivative-free methods for non-simple zeros have the following implemented:
 
 ```@docs
 Roots.King
+Roots.Order1B
 Roots.Esser
+Roots.Order2B
 ```
 
 
@@ -300,12 +309,13 @@ Roots.dfree
 The initial naming scheme used `fzero` instead  of `fzeros`, following the name of the  MATLAB function [fzero](https://www.mathworks.com/help/matlab/ref/fzero.html). This interface  is not recommended, but, for now, still maintained.
 
 ```@docs
-Roots.fzero
+fzero
+fzeros
 ```
 
 ## Tracking iterations
 
-It is possible to add the keyword argument `verbose=true`  when calling the `find_zero` function to get detailed information about the solution and data from each iteration. To save this data a `Tracks` object may be passed in to `tracks`.
+It is possible to add the keyword argument `verbose=true`  when calling the `find_zero` function to get detailed information about the solution and data from each iteration. To save this data a `Tracks`object may be passed in to `tracks`.
 
 ----
 

src/Bracketing/alefeld_potra_shi.jl

@@ -7,6 +7,7 @@
 
 ## --------------------------------------------------
 
+#=
 """
     AbstractAlefeldPotraShi
 
@@ -16,6 +17,7 @@ The `update_step` method calls a `calculateΔ` method that can be customized to
 
 This implementation deviates slightly from the printed algorithm, as it may use an initial call to `_middle` rather than a secant step, depending on the signs of ``a`` and ``b``.
 """
+=#
 abstract type AbstractAlefeldPotraShi <: AbstractBracketingMethod end
 
 initial_fncalls(::AbstractAlefeldPotraShi) = 3 # worst case assuming fx₀, fx₁,fc must be computed

src/DerivativeFree/esser.jl

@@ -1,6 +1,5 @@
 ### Order2B() Esser method
 """
-    Roots.Order2B()
     Roots.Esser()
 
 Esser's method. This is a quadratically convergent method that, like
@@ -29,6 +28,12 @@ find_zero(g, x0, Roots.Order2B(), verbose=true) #  4 / 10
 ```
 """
 struct Esser <: AbstractSecantMethod end
+
+"""
+    Roots.Order2B()
+
+[`Esser`](@ref) method with guarded secant step.
+"""
 struct Order2B <: AbstractSecantMethod end
 
 function update_state(

src/DerivativeFree/king.jl

@@ -1,5 +1,4 @@
 """
-    Roots.Order1B()
     Roots.King()
 
 A superlinear (order `1.6...`) modification of the secant method for multiple roots.
@@ -15,6 +14,12 @@ The *asymptotic* error, `eᵢ = xᵢ - α`, is given by
 
 """
 struct King <: AbstractSecantMethod end
+
+"""
+    Roots.Order1B()
+
+[`King`](@ref) method with guarded secant step.
+"""
 struct Order1B <: AbstractSecantMethod end
 
 struct KingState{T,S} <: AbstractUnivariateZeroState{T,S}

src/DerivativeFree/steffensen.jl

@@ -1,6 +1,5 @@
 """
     Steffensen()
-    Order2()
 
 
 The quadratically converging
@@ -17,6 +16,12 @@ The error, `eᵢ - α`, satisfies
 `eᵢ₊₁ = f[xᵢ, xᵢ+fᵢ, α] / f[xᵢ,xᵢ+fᵢ] ⋅ (1 - f[xᵢ,α] ⋅ eᵢ²`
 """
 struct Steffensen <: AbstractSecantMethod end
+
+"""
+    Order2
+
+[`Steffensen`](@ref) with a guard on the secant step.
+"""
 struct Order2 <: AbstractSecantMethod end
 
 function update_state(

src/Roots.jl

@@ -1,3 +1,11 @@
+"""
+`Roots`. A package for solving `f(x) = 0` for  univariate, scalar functions.
+
+The basic methods are
+* [`find_zero`](@ref) for using one of several methods to identify a zero
+* [`ZeroProblem`](@ref) for solving for a zero using the `CommonSolve` interface
+* [`find_zeros`](@ref) for heuristically identifying all zeros in a specified interval
+"""
 module Roots
 
 if isdefined(Base, :Experimental) && isdefined(Base.Experimental, Symbol("@optlevel"))

src/alternative_interfaces.jl

@@ -26,7 +26,7 @@ See also `Roots.newton((f,fp), x0)` and `Roots.newton(fΔf, x0)` for simpler imp
 newton(f, fp, x0; kwargs...) = find_zero((f, fp), x0, Newton(); kwargs...)
 
 ## --------------------------------------------------
-
+#=
 """
     Roots.halley(f, fp, fpp, x0; kwargs...)
 
@@ -50,8 +50,10 @@ Keyword arguments are passed to `find_zero` using the `Roots.Halley()` method.
 
 
 """
+=#
 halley(f, fp, fpp, x0; kwargs...) = find_zero((f, fp, fpp), x0, Halley(); kwargs...)
 
+#=
 """
     Roots.quadratic_inverse(f, fp, fpp, x0; kwargs...)
 
@@ -75,6 +77,7 @@ Keyword arguments are passed to `find_zero` using the `Roots.QuadraticInverse()`
 
 
 """
+=#
 quadratic_inverse(f, fp, fpp, x0; kwargs...) =
     find_zero((f, fp, fpp), x0, QuadraticInverse(); kwargs...)
 
@@ -245,17 +248,14 @@ end
 
 ## fzeros
 """
-
-`fzeros(f, a, b; kwargs...)`
+    fzeros(f, a, b; kwargs...)
+    fzeros(f, ab; kwargs...)
 
 Searches for all zeros of `f` within an interval `(a,b)`. Assume neither `a` or `b` is a zero.
 
-Dispatches to `find_zeros(f, a, b; kwargs...)`.
+Compatability interface for [`find_zeros`](@ref).
 """
 function fzeros(f, a::Number, b::Number; kwargs...)
     find_zeros(FnWrapper(f), float(a), float(b); kwargs...)
 end
-fzeros(f, bracket::Vector{T}; kwargs...) where {T<:Number} =
-    fzeros(f, bracket[1], bracket[2]; kwargs...)
-fzeros(f, bracket::Tuple{T,S}; kwargs...) where {T<:Number,S<:Number} =
-    fzeros(f, bracket[1], bracket[2]; kwargs...)
+fzeros(f, ab; kwargs...) = fzeros(f, _extrema(ab)...; kwargs...)