[docs] add deprecation notes to the legacy nonlinear interface docstrings

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 = sort(_exported_symbols(current_module); by = config.sort_by)
+    for (key, type) in vcat(key_types, modules)
         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") || ret 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,
 )
 
 # ==============================================================================

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

src/nlp.jl

@@ -14,6 +14,10 @@ otherwise return `nothing`.
 
 If `force`, always return a [`MOI.Nonlinear.Model`](@ref), and if one does not
 exist for the model, create an empty one.
+
+!!! compat
+    This function is part of the legacy nonlinear interface. Consider using the
+    new nonlinear interface documented in [Nonlinear Modeling](@ref).
 """
 function nonlinear_model(model::GenericModel; force::Bool = false)
     if force
@@ -146,6 +150,10 @@ optimization sense `sense`.
 This function is most useful if the expression `expr` is generated
 programmatically, and you cannot use [`@NLobjective`](@ref).
 
+!!! compat
+    This function is part of the legacy nonlinear interface. Consider using the
+    new nonlinear interface documented in [Nonlinear Modeling](@ref).
+
 ## Notes
 
  * You must interpolate the variables directly into the expression `expr`.
@@ -191,6 +199,10 @@ end
 A struct to represent a nonlinear parameter.
 
 Create a parameter using [`@NLparameter`](@ref).
+
+!!! compat
+    This type is part of the legacy nonlinear interface. Consider using the
+    new nonlinear interface documented in [Nonlinear Modeling](@ref).
 """
 struct NonlinearParameter <: AbstractJuMPScalar
     model::Model
@@ -211,6 +223,10 @@ end
     add_nonlinear_parameter(model::Model, value::Real)
 
 Add an anonymous parameter to the model.
+
+!!! compat
+    This function is part of the legacy nonlinear interface. Consider using the
+    new nonlinear interface documented in [Nonlinear Modeling](@ref).
 """
 function add_nonlinear_parameter(model::Model, value::Real)
     nlp = nonlinear_model(model; force = true)::MOI.Nonlinear.Model
@@ -252,6 +268,10 @@ end
 
 Store the value `v` in the nonlinear parameter `p`.
 
+!!! compat
+    This function is part of the legacy nonlinear interface. Consider using the
+    new nonlinear interface documented in [Nonlinear Modeling](@ref).
+
 ## Example
 
 ```jldoctest
@@ -283,6 +303,10 @@ end
 A struct to represent a nonlinear expression.
 
 Create an expression using [`@NLexpression`](@ref).
+
+!!! compat
+    This type is part of the legacy nonlinear interface. Consider using the
+    new nonlinear interface documented in [Nonlinear Modeling](@ref).
 """
 struct NonlinearExpression <: AbstractJuMPScalar
     model::Model
@@ -314,6 +338,10 @@ Add a nonlinear expression `expr` to `model`.
 This function is most useful if the expression `expr` is generated
 programmatically, and you cannot use [`@NLexpression`](@ref).
 
+!!! compat
+    This function is part of the legacy nonlinear interface. Consider using the
+    new nonlinear interface documented in [Nonlinear Modeling](@ref).
+
 ## Notes
 
  * You must interpolate the variables directly into the expression `expr`.
@@ -341,8 +369,6 @@ end
 Return the value of the `NonlinearExpression` `ex` associated with result index
 `result` of the most-recent solution returned by the solver.
 
-Replaces `getvalue` for most use cases.
-
 See also: [`result_count`](@ref).
 """
 function value(ex::NonlinearExpression; result::Int = 1)
@@ -401,6 +427,10 @@ const NonlinearConstraintIndex = MOI.Nonlinear.ConstraintIndex
 
 """
     NonlinearConstraintRef
+
+!!! compat
+    This type is part of the legacy nonlinear interface. Consider using the
+    new nonlinear interface documented in [Nonlinear Modeling](@ref).
 """
 const NonlinearConstraintRef =
     ConstraintRef{Model,MOI.Nonlinear.ConstraintIndex}
@@ -448,6 +478,10 @@ Add a nonlinear constraint described by the Julia expression `ex` to `model`.
 This function is most useful if the expression `ex` is generated
 programmatically, and you cannot use [`@NLconstraint`](@ref).
 
+!!! compat
+    This function is part of the legacy nonlinear interface. Consider using the
+    new nonlinear interface documented in [Nonlinear Modeling](@ref).
+
 ## Notes
 
  * You must interpolate the variables directly into the expression `expr`.
@@ -500,6 +534,14 @@ end
     num_nonlinear_constraints(model::GenericModel)
 
 Returns the number of nonlinear constraints associated with the `model`.
+
+!!! compat
+    This function is part of the legacy nonlinear interface. Consider using the
+    new nonlinear interface documented in [Nonlinear Modeling](@ref).
+
+This function counts only the constraints added with [`@NLconstraint`](@ref) and
+[`add_nonlinear_constraint`](@ref). It does not count [`GenericNonlinearExpr`](@ref)
+constraints.
 """
 function num_nonlinear_constraints(model::GenericModel)
     nlp_model = nonlinear_model(model)
@@ -514,6 +556,14 @@ end
 
 Return a vector of all nonlinear constraint references in the model in the
 order they were added to the model.
+
+!!! compat
+    This function is part of the legacy nonlinear interface. Consider using the
+    new nonlinear interface documented in [Nonlinear Modeling](@ref).
+
+This function returns only the constraints added with [`@NLconstraint`](@ref) and
+[`add_nonlinear_constraint`](@ref). It does not return [`GenericNonlinearExpr`](@ref)
+constraints.
 """
 function all_nonlinear_constraints(model::GenericModel)
     nlp_model = nonlinear_model(model)
@@ -582,6 +632,10 @@ end
     nonlinear_dual_start_value(model::Model)
 
 Return the current value of the MOI attribute [`MOI.NLPBlockDualStart`](@ref).
+
+!!! compat
+    This function is part of the legacy nonlinear interface. Consider using the
+    new nonlinear interface documented in [Nonlinear Modeling](@ref).
 """
 function nonlinear_dual_start_value(model::Model)
     return MOI.get(model, MOI.NLPBlockDualStart())
@@ -595,6 +649,10 @@ end
 
 Set the value of the MOI attribute [`MOI.NLPBlockDualStart`](@ref).
 
+!!! compat
+    This function is part of the legacy nonlinear interface. Consider using the
+    new nonlinear interface documented in [Nonlinear Modeling](@ref).
+
 The start vector corresponds to the Lagrangian duals of the nonlinear
 constraints, in the order given by [`all_nonlinear_constraints`](@ref). That is, you
 must pass a single start vector corresponding to all of the nonlinear
@@ -666,6 +724,10 @@ Register the user-defined function `f` that takes `dimension` arguments in
 The function `f` must support all subtypes of `Real` as arguments. Do not assume
 that the inputs are `Float64`.
 
+!!! compat
+    This function is part of the legacy nonlinear interface. Consider using the
+    new nonlinear interface documented in [Nonlinear Modeling](@ref).
+
 ## Notes
 
  * For this method, you must explicitly set `autodiff = true`, because no
@@ -737,6 +799,10 @@ Register the user-defined function `f` that takes `dimension` arguments in
 The functions `f`and `∇f` must support all subtypes of `Real` as arguments. Do
 not assume that the inputs are `Float64`.
 
+!!! compat
+    This function is part of the legacy nonlinear interface. Consider using the
+    new nonlinear interface documented in [Nonlinear Modeling](@ref).
+
 ## Notes
 
  * If the function `f` is univariate (i.e., `dimension == 1`), `∇f` must return
@@ -834,6 +900,10 @@ hessian function `∇²f`.
 `∇f` and `∇²f` must return numbers corresponding to the first- and second-order
 derivatives of the function `f` respectively.
 
+!!! compat
+    This function is part of the legacy nonlinear interface. Consider using the
+    new nonlinear interface documented in [Nonlinear Modeling](@ref).
+
 ## Notes
 
  * Because automatic differentiation is not used, you can assume the inputs are