[docs] add deprecation notes to the legacy nonlinear interface docstr…

…ings (#3711)

docs/DocumenterReference.jl

@@ -24,6 +24,7 @@ struct _Config
     root::String
     subdirectory::String
     modules::Dict{Module,<:Vector}
+    sort_by::Function
 end
 
 const CONFIG = _Config[]
@@ -37,6 +38,7 @@ Documenter.Selectors.order(::Type{APIBuilder}) = 0.0
         root::String,
         subdirectory::String,
         modules::Dict{Module,Vector{Pair{String,DocType}}},
+        sort_by::Function = identity,
     )
 
 Automatically creates the API reference documentation for `current_module` and
@@ -61,6 +63,7 @@ function automatic_reference_documentation(;
     root::String,
     subdirectory::String,
     modules::Vector,
+    sort_by::Function = identity,
 )
     _to_extras(m::Module) = m => Any[]
     _to_extras(m::Pair) = m
@@ -73,6 +76,7 @@ function automatic_reference_documentation(;
             root,
             subdirectory,
             modules = _modules,
+            sort_by,
         )
         push!(list_of_pages, "$current_module" => pages)
     end
@@ -84,8 +88,9 @@ function _automatic_reference_documentation(
     root::String,
     subdirectory::String,
     modules::Dict{Module,<:Vector},
+    sort_by::Function,
 )
-    push!(CONFIG, _Config(current_module, root, subdirectory, modules))
+    push!(CONFIG, _Config(current_module, root, subdirectory, modules, sort_by))
     return "$subdirectory/$current_module.md"
 end
 
@@ -126,7 +131,8 @@ end
 function _iterate_over_symbols(f, config)
     current_module = config.current_module
     modules = get(config.modules, config.current_module, Any[])
-    for (key, type) in vcat(_exported_symbols(current_module), modules)
+    key_types = vcat(_exported_symbols(current_module), modules)
+    for (key, type) in sort!(key_types; by = config.sort_by)
         if key isa Symbol
             doc = Base.Docs.doc(Base.Docs.Binding(current_module, key))
             if occursin("No documentation found.", string(doc))

docs/make.jl

@@ -211,6 +211,31 @@ pushfirst!(_LIST_OF_EXTENSIONS, "Introduction" => "extensions/introduction.md")
 
 include(joinpath(@__DIR__, "DocumenterReference.jl"))
 
+function sort_by_api_fn((key, type))
+    deprecated_methods = [
+        :add_nonlinear_constraint,
+        :add_nonlinear_expression,
+        :add_nnonlinear_parameter,
+        :all_nonlinear_constraints,
+        :get_optimizer_attribute,
+        :nonlinear_constraint_string,
+        :nonlinear_dual_start_value,
+        :nonlinear_expr_string,
+        :nonlinear_model,
+        :num_nonlinear_constraints,
+        :register,
+        :set_nonlinear_dual_start_value,
+        :set_nonlinear_objective,
+        :set_optimizer_attribute,
+        :set_value,
+        :NonlinearConstraintIndex,
+        :NonlinearConstraintRef,
+        :NonlinearExpression,
+        :NonlinearParameter,
+    ]
+    return startswith("$key", "@NL") || key in deprecated_methods
+end
+
 jump_api_reference = DocumenterReference.automatic_reference_documentation(;
     root = joinpath(@__DIR__, "src"),
     subdirectory = "api",
@@ -265,6 +290,7 @@ jump_api_reference = DocumenterReference.automatic_reference_documentation(;
                 DocumenterReference.DOCTYPE_STRUCT,
         ],
     ],
+    sort_by = sort_by_api_fn,
 )
 
 # ==============================================================================

docs/src/manual/nonlinear.md

@@ -8,14 +8,6 @@ DocTestFilters = [r"≤|<=", r"≥|>=", r" == | = ", r" ∈ | in ", r"MathOptInt
 
 # Nonlinear Modeling
 
-!!! warning
-    This page describes a new nonlinear interface to JuMP. It replaces the
-    legacy `@NL` interface, which is documented at [Nonlinear Modeling (Legacy)](@ref).
-    The API described below is stable, and it will not break with future 1.X
-    releases of JuMP. However, solver support may be limited, and there may be
-    gaps in functionality compared with the legacy interface. To report a bug,
-    or request a missing feature, please [open an issue](https://github.com/jump-dev/JuMP.jl/issues/new/choose).
-
 JuMP has support for nonlinear (convex and nonconvex) optimization problems.
 JuMP is able to automatically provide exact, sparse second-order derivatives to
 solvers. This information can improve solver accuracy and performance.

src/macros/@NL.jl

@@ -233,6 +233,11 @@ end
 Add a nonlinear objective to `model` with optimization sense `sense`.
 `sense` must be `Max` or `Min`.
 
+!!! compat
+    This macro is part of the legacy nonlinear interface. Consider using the
+    new nonlinear interface documented in [Nonlinear Modeling](@ref). In most
+    cases, you can replace `@NLobjective` with [`@objective`](@ref).
+
 ## Example
 
 ```jldoctest
@@ -269,7 +274,14 @@ end
     @NLconstraint(model::GenericModel, expr)
 
 Add a constraint described by the nonlinear expression `expr`. See also
-[`@constraint`](@ref). For example:
+[`@constraint`](@ref).
+
+!!! compat
+    This macro is part of the legacy nonlinear interface. Consider using the
+    new nonlinear interface documented in [Nonlinear Modeling](@ref). In most
+    cases, you can replace `@NLconstraint` with [`@constraint`](@ref).
+
+## Example
 
 ```jldoctest
 julia> model = Model();
@@ -338,6 +350,11 @@ multiple lines wrapped in a `begin ... end` block.
 
 The macro returns a tuple containing the constraints that were defined.
 
+!!! compat
+    This macro is part of the legacy nonlinear interface. Consider using the
+    new nonlinear interface documented in [Nonlinear Modeling](@ref). In most
+    cases, you can replace `@NLconstraints` with [`@constraints`](@ref).
+
 ## Example
 
 ```jldoctest
@@ -372,7 +389,14 @@ end
     @NLexpression(args...)
 
 Efficiently build a nonlinear expression which can then be inserted in other
-nonlinear constraints and the objective. See also [`@expression`]. For example:
+nonlinear constraints and the objective. See also [`@expression`].
+
+!!! compat
+    This macro is part of the legacy nonlinear interface. Consider using the
+    new nonlinear interface documented in [Nonlinear Modeling](@ref). In most
+    cases, you can replace `@NLexpression` with [`@expression`](@ref).
+
+## Example
 
 ```jldoctest api_nlexpression
 julia> model = Model();
@@ -456,6 +480,11 @@ multiple lines wrapped in a `begin ... end` block.
 
 The macro returns a tuple containing the expressions that were defined.
 
+!!! compat
+    This macro is part of the legacy nonlinear interface. Consider using the
+    new nonlinear interface documented in [Nonlinear Modeling](@ref). In most
+    cases, you can replace `@NLexpressions` with [`@expressions`](@ref).
+
 ## Example
 
 ```jldoctest
@@ -549,6 +578,12 @@ Create and return an anonymous collection of nonlinear parameters attached to
 the model `model` with initial value set to `value_expr` (may depend on index
 sets). Uses the same syntax for specifying index sets as [`@variable`](@ref).
 
+!!! compat
+    This macro is part of the legacy nonlinear interface. Consider using the
+    new nonlinear interface documented in [Nonlinear Modeling](@ref). In most
+    cases, you can replace a call like `@NLparameter(model, p == value)` with
+    `@variable(model, p in Parameter(value))`.
+
 ## Example
 
 ```jldoctest
@@ -638,6 +673,22 @@ be placed on separate lines as in the following example.
 
 The macro returns a tuple containing the parameters that were defined.
 
+!!! compat
+    This macro is part of the legacy nonlinear interface. Consider using the
+    new nonlinear interface documented in [Nonlinear Modeling](@ref). In most
+    cases, you can replace a call like
+    ```julia
+    @NLparameters(model, begin
+        p == value
+    end)
+    ```
+    with
+    ```julia
+    @variables(model, begin
+        p in Parameter(value)
+    end)
+    ```
+
 ## Example
 
 ```jldoctest