[docs] update vale to v3.0.5 (#2403)

Author: odow

.github/workflows/documentation.yml

@@ -33,11 +33,10 @@ jobs:
           path: ${{ github.workspace }}/latex-debug-logs
       - uses: errata-ai/vale-action@reviewdog
         with:
-          # TODO(odow): at some point, update to vale@3
-          version: 2.30.0
-          files: docs/src
+          version: 3.0.5
+          files: all
           fail_on_error: true
           filter_mode: nofilter
-          vale_flags: "--config=docs/.vale.ini"
+          vale_flags: "--config=.vale.ini"
         env:
           GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

.vale.ini

@@ -0,0 +1,22 @@
+StylesPath = docs/styles
+MinAlertLevel = warning
+
+Vocab = JuMP
+
+[*.jl]
+BasedOnStyles = Vale, Google
+
+# TODO(odow): fix all of these
+Google.Ellipses = OFF
+Google.Exclamation = OFF
+Google.FirstPerson = OFF
+Google.OptionalPlurals = OFF
+Google.Units = OFF
+Vale.Spelling = OFF
+
+[*.md]
+BasedOnStyles = Vale, Google
+
+[*]
+TokenIgnores = (\$.+?\$), \]\(@(ref|id).+?\)
+Google.Quotes = OFF

docs/.vale.ini

@@ -149,8 +149,8 @@ write(joinpath(@__DIR__, "src", "MathOptInterface.pdf"), "")
     linkcheck_ignore = [
         # Ignore the PDF link, because it hasn't been built yet.
         "MathOptInterface.pdf",
-        # Ignore tags, because preping for a new release will otherwise cause it
-        # to fail.
+        # Ignore tags, because prepping for a new release will otherwise cause
+        # it to fail.
         r"https://github.com/jump-dev/MathOptInterface.jl/releases/tag/v([0-9]).([0-9]+).([0-9]+)",
         # Ignore issue and pull request links, because there are many of them,
         # and they sometimes time-out the linkcheck.
@@ -178,8 +178,8 @@ if _PDF
         build = "latex_build",
         pages = _PAGES,
     )
-    # Hack for deploying: copy the pdf (and only the PDF) into the HTML build
-    # directory! We don't want to copy everything in `latex_build` because it
+    # Hack for deploying: copy the PDF (and only the PDF) into the HTML build
+    # directory. We don't want to copy everything in `latex_build` because it
     # includes lots of extraneous LaTeX files.
     cp(
         joinpath(@__DIR__, "latex_build", "MathOptInterface.pdf"),

docs/make.jl

@@ -7,13 +7,17 @@ bugfixe(?s)
 datastructure
 docstring(?s)
 doctest
-enum
+[Ee]num
 errored
 flamegraph
 getters
 [Jj]ulia
+linkcheck
+nonlinearly
 [Pp]recompil(ation|(e(?d)))
 subexpression(?s)
+sublicense
+textualist
 
 % JuMP-related vocab
 [Cc]anonicaliz(e|ation|ing)
@@ -27,6 +31,7 @@ unboundedness
 [Un]nivariate
 
 % Other
+Codecov
 Clp
 Gurobi
 GZip
@@ -35,3 +40,4 @@ JSONSchema
 MOI
 PATHSolver
 preprint
+Lubin

docs/styles/Vocab/JuMP-Vocab/accept.txt renamed to docs/styles/config/vocabularies/JuMP/accept.txt

@@ -75,8 +75,8 @@ uses a limited set of bridges that are:
   2. generally applicable for all optimizers.
 
 For some optimizers however, it is useful to add additional bridges, such as
-those that are implemented in external packages (e.g., within the solver package
-itself) or only apply in certain circumstances (e.g.,
+those that are implemented in external packages (for example, within the solver package
+itself) or only apply in certain circumstances (for example,
 [`Constraint.SOCtoNonConvexQuadBridge`](@ref)).
 
 Such optimizers should implement the `ListOfNonstandardBridges` attribute to
@@ -108,7 +108,7 @@ end
 
 ### An optimizer defining an internal bridge
 
-Suppose an optimizer can exploit specific structure of a constraint, e.g., it
+Suppose an optimizer can exploit specific structure of a constraint, for example, it
 can exploit the structure of the matrix `A` in the linear system of equations
 `A * x = b`.
 

src/Bridges/Bridges.jl

@@ -11,8 +11,8 @@ An abstract type that simplifies the creation of other bridges.
 
 !!! warning
     `T` must be a `AbstractFloat` type because otherwise `typemin` and `typemax`
-    would either be not implemented (e.g. `BigInt`), or would not give infinite
-    value (e.g. `Int`). For this reason, this bridge is only added to
+    would either be not implemented (for example, `BigInt`), or would not give infinite
+    value (for example, `Int`). For this reason, this bridge is only added to
     [`MOI.Bridges.full_bridge_optimizer`](@ref) when `T` is a subtype of
     `AbstractFloat`.
 """

src/Bridges/Constraint/bridges/ltgt_to_interval.jl

@@ -81,7 +81,7 @@ function bridge_constraint(
                 "Unable to transform a quadratic constraint into a " *
                 "second-order cone constraint because the quadratic " *
                 "constraint is not strongly convex.\n\nConvex constraints " *
-                "that are not strongly convex (i.e., the matrix is positive " *
+                "that are not strongly convex (that is, the matrix is positive " *
                 "semidefinite but not positive definite) are not supported " *
                 "yet.\n\nNote that a quadratic equality constraint is " *
                 "non-convex.",
@@ -347,7 +347,7 @@ end
 #                       = -u * (z^T Q z/2 + a^T z + b)
 # So the dual of the quadratic constraint is `-u`, so that the contribution
 # to the lagrangian function of both the quadratic and RotatedSOC formulation
-# is exactly the same. Q.E.D.
+# is exactly the same.
 function MOI.get(
     model::MOI.ModelLike,
     attr::Union{MOI.ConstraintDual,MOI.ConstraintDualStart},

src/Bridges/Constraint/bridges/quad_to_soc.jl

@@ -175,7 +175,7 @@ end
 """
     keys_of_type(map::Map, C::Type{<:MOI.ConstraintIndex})
 
-Return a list of all the keys of type `C` in `map` in order order in which they
+Return a list of all the keys of type `C` in `map` in order in which they
 were created with `add_key_for_bridge`.
 """
 function keys_of_type(map::Map, C::Type{MOI.ConstraintIndex{F,S}}) where {F,S}

src/Bridges/Constraint/map.jl

@@ -288,7 +288,7 @@ Record that a constraint `vi`-in-`set` is added and throws if a lower or upper b
 is set by this constraint and such bound has already been set for `vi`.
 """
 function MOI.add_constraint(::Map, ::MOI.VariableIndex, ::MOI.AbstractScalarSet)
-    # Nothing to do as this is is not recognized as setting a lower or upper bound
+    # Nothing to do as this is not recognized as setting a lower or upper bound
 end
 
 # We cannot use `SUPPORTED_VARIABLE_SCALAR_SETS` because
@@ -327,7 +327,7 @@ function MOI.delete(
     ::Map,
     ci::MOI.ConstraintIndex{MOI.VariableIndex,<:MOI.AbstractScalarSet},
 )
-    # Nothing to do as this is is not recognized as setting a lower or upper bound
+    # Nothing to do as this is not recognized as setting a lower or upper bound
 end
 
 function MOI.delete(
@@ -581,7 +581,7 @@ function throw_if_cannot_unbridge(map::Map)
     if map.unbridged_function === nothing
         error(
             "Cannot unbridge function because some variables are bridged by",
-            " variable bridges that do not support reverse mapping, e.g.,",
+            " variable bridges that do not support reverse mapping, for example,",
             " `ZerosBridge`.",
         )
     end

src/Bridges/Variable/map.jl

@@ -1534,7 +1534,7 @@ function MOI.supports(
         if is_bridged(b, S)
             # If S needs to be bridged, it usually means that either there is a
             # variable bridge, or that there is a free variable followed by a
-            # constraint bridge (i.e., the two cases handled below).
+            # constraint bridge (that is, the two cases handled below).
             #
             # However, it might be the case, like the tests in
             # Variable/flip_sign.jl, that the model supports F-in-S constraints,
@@ -2216,7 +2216,7 @@ function bridged_function(b::AbstractBridgeOptimizer, func::MOI.VariableIndex)
     # Should not be called by `add_constraint` as it force-bridges it
     # but could be called by attributes
     if is_bridged(b, func)
-        # It could be solved by force-bridging the attribues (e.g. objective).
+        # It could be solved by force-bridging the attribues (for example, objective).
         error("Using bridged variable in `VariableIndex` function.")
     end
     return func
@@ -2349,7 +2349,7 @@ function unbridged_constraint_function end
 
 # The purpose of unbridged_constraint_function is to convert the result of
 # ConstraintFunction into the un-bridged form. Since variable bridges create
-# substitution rules which are scalar functions, e.g., `x => y_1 - y_2`, if the
+# substitution rules which are scalar functions, for example, `x => y_1 - y_2`, if the
 # result is a VariableIndex or an AbstractVectorFunction we can return the
 # unbridged function:
 

src/Bridges/bridge_optimizer.jl

@@ -94,14 +94,14 @@ The number inside each pair of brackets is an index of the node in the
 hyper-graph.
 
 Note that this hyper-graph is the full list of possible transformations. When
-the bridged model is created, we select the shortest hyper-path(s) from this
+the bridged model is created, we select the shortest hyper-path from this
 graph, so many nodes may be un-used.
 
 To see which nodes are used, call [`print_active_bridges`](@ref).
 
 For more information, see Legat, B., Dowson, O., Garcia, J., and Lubin, M.
 (2020).  "MathOptInterface: a data structure for mathematical optimization
-problems." URL: [https://arxiv.org/abs/2002.03447](https://arxiv.org/abs/2002.03447)
+problems." [URL](https://arXiv.org/abs/2002.03447)
 """
 function print_graph(io::IO, b::LazyBridgeOptimizer; kwargs...)
     println(io, b.graph)

src/Bridges/debug.jl

@@ -12,7 +12,7 @@ import MathOptInterface as MOI
 # Julia 1.6 removes Grisu from Base. Previously, we went
 #   _print_shortest(io, x) = Base.Grisu.print_shortest(io, x)
 # To avoid adding Grisu as a dependency, use the following printing heuristic.
-# TODO(odow): consider printing 1.0 as 1.0 instead of 1, i.e., without the
+# TODO(odow): consider printing 1.0 as 1.0 instead of 1, that is, without the
 # rounding branch.
 function _print_shortest(io::IO, x::Float64)
     if x == -Inf

src/FileFormats/LP/LP.jl

@@ -426,7 +426,7 @@
                     }
                 }
             }, {
-                "description": "The function `0.5x'Qx + a'x + b`, where `a` is a sparse vector of `ScalarAffineTerm`s in `affine_terms`, `b` is the scalar `constant`, and `Q` is a symmetric matrix specified by a list of `ScalarQuadraticTerm`s in `quadratic_terms`. Duplicate indices in `affine_terms` and `quadratic` are accepted, and the corresponding coefficients are summed together. Mirrored indices in `quadratic_terms` (i.e., `(i,j)` and `(j, i)`) are considered duplicates; only one need to be specified.",
+                "description": "The function `0.5x'Qx + a'x + b`, where `a` is a sparse vector of `ScalarAffineTerm`s in `affine_terms`, `b` is the scalar `constant`, and `Q` is a symmetric matrix specified by a list of `ScalarQuadraticTerm`s in `quadratic_terms`. Duplicate indices in `affine_terms` and `quadratic` are accepted, and the corresponding coefficients are summed together. Mirrored indices in `quadratic_terms` (that is, `(i,j)` and `(j, i)`) are considered duplicates; only one need to be specified.",
                 "examples": ["{\"type\": \"ScalarQuadraticFunction\", \"constant\": 1.0, \"affine_terms\": [{\"coefficient\": 2.5, \"variable\": \"x\"}], \"quadratic_terms\": [{\"coefficient\": 2.0, \"variable_1\": \"x\", \"variable_2\": \"y\"}]}"],
                 "required": ["constant", "affine_terms", "quadratic_terms"],
                 "properties": {
@@ -813,7 +813,7 @@
                     }
                 }
             }, {
-                "description": "{[t, X] ∈ R^{1 + d(d+1)/2} : t ≤ det(X)^{1/d}}, where the matrix `X` is represented in the same symmetric packed format as in the `PositiveSemidefiniteConeTriangle`. The argument `side_dimension` is the side dimension of the matrix `X`, i.e., its number of rows or columns.",
+                "description": "{[t, X] ∈ R^{1 + d(d+1)/2} : t ≤ det(X)^{1/d}}, where the matrix `X` is represented in the same symmetric packed format as in the `PositiveSemidefiniteConeTriangle`. The argument `side_dimension` is the side dimension of the matrix `X`, that is, its number of rows or columns.",
                 "examples": ["{\"type\": \"RootDetConeTriangle\", \"side_dimension\": 2}"],
                 "required": ["side_dimension"],
                 "properties": {
@@ -826,7 +826,7 @@
                     }
                 }
             }, {
-                "description": "{[t, X] ∈ R^{1 + d^2} : t ≤ det(X)^{1/d}, X symmetric}, where the matrix `X` is represented in the same symmetric packed format as in the `PositiveSemidefiniteConeSquare`. The argument `side_dimension` is the side dimension of the matrix `X`, i.e., its number of rows or columns.",
+                "description": "{[t, X] ∈ R^{1 + d^2} : t ≤ det(X)^{1/d}, X symmetric}, where the matrix `X` is represented in the same symmetric packed format as in the `PositiveSemidefiniteConeSquare`. The argument `side_dimension` is the side dimension of the matrix `X`, that is, its number of rows or columns.",
                 "examples": ["{\"type\": \"RootDetConeSquare\", \"side_dimension\": 2}"],
                 "required": ["side_dimension"],
                 "properties": {
@@ -839,7 +839,7 @@
                     }
                 }
             }, {
-                "description": "{[t, u, X] ∈ R^{2 + d(d+1)/2} : t ≤ u log(det(X/u)), u > 0}, where the matrix `X` is represented in the same symmetric packed format as in the `PositiveSemidefiniteConeTriangle`. The argument `side_dimension` is the side dimension of the matrix `X`, i.e., its number of rows or columns.",
+                "description": "{[t, u, X] ∈ R^{2 + d(d+1)/2} : t ≤ u log(det(X/u)), u > 0}, where the matrix `X` is represented in the same symmetric packed format as in the `PositiveSemidefiniteConeTriangle`. The argument `side_dimension` is the side dimension of the matrix `X`, that is, its number of rows or columns.",
                 "examples": ["{\"type\": \"LogDetConeTriangle\", \"side_dimension\": 2}"],
                 "required": ["side_dimension"],
                 "properties": {
@@ -852,7 +852,7 @@
                     }
                 }
             }, {
-                "description": "{[t, u, X] ∈ R^{2 + d^2} : t ≤ u log(det(X/u)), X symmetric, u > 0}, where the matrix `X` is represented in the same symmetric packed format as in the `PositiveSemidefiniteConeSquare`. The argument `side_dimension` is the side dimension of the matrix `X`, i.e., its number of rows or columns.",
+                "description": "{[t, u, X] ∈ R^{2 + d^2} : t ≤ u log(det(X/u)), X symmetric, u > 0}, where the matrix `X` is represented in the same symmetric packed format as in the `PositiveSemidefiniteConeSquare`. The argument `side_dimension` is the side dimension of the matrix `X`, that is, its number of rows or columns.",
                 "examples": ["{\"type\": \"LogDetConeSquare\", \"side_dimension\": 2}"],
                 "required": ["side_dimension"],
                 "properties": {
@@ -1019,7 +1019,7 @@
                     }
                 }
             }, {
-                "description": "The set corresponding to a mixed complementarity constraint. Complementarity constraints should be specified with an AbstractVectorFunction-in-Complements(dimension) constraint. The dimension of the vector-valued function `F` must be `dimension`. This defines a complementarity constraint between the scalar function `F[i]` and the variable in `F[i + dimension/2]`. Thus, `F[i + dimension/2]` must be interpretable as a single variable `x_i` (e.g., `1.0 * x + 0.0`). The mixed complementarity problem consists of finding `x_i` in the interval `[lb, ub]` (i.e., in the set `Interval(lb, ub)`), such that the following holds: 1. `F_i(x) == 0` if `lb_i < x_i < ub_i`; 2. `F_i(x) >= 0` if `lb_i == x_i`; 3. `F_i(x) <= 0` if `x_i == ub_i`. Classically, the bounding set for `x_i` is `Interval(0, Inf)`, which recovers: `0 <= F_i(x) ⟂ x_i >= 0`, where the `⟂` operator implies `F_i(x) * x_i = 0`.",
+                "description": "The set corresponding to a mixed complementarity constraint. Complementarity constraints should be specified with an AbstractVectorFunction-in-Complements(dimension) constraint. The dimension of the vector-valued function `F` must be `dimension`. This defines a complementarity constraint between the scalar function `F[i]` and the variable in `F[i + dimension/2]`. Thus, `F[i + dimension/2]` must be interpretable as a single variable `x_i` (for example, `1.0 * x + 0.0`). The mixed complementarity problem consists of finding `x_i` in the interval `[lb, ub]` (that is, in the set `Interval(lb, ub)`), such that the following holds: 1. `F_i(x) == 0` if `lb_i < x_i < ub_i`; 2. `F_i(x) >= 0` if `lb_i == x_i`; 3. `F_i(x) <= 0` if `x_i == ub_i`. Classically, the bounding set for `x_i` is `Interval(0, Inf)`, which recovers: `0 <= F_i(x) ⟂ x_i >= 0`, where the `⟂` operator implies `F_i(x) * x_i = 0`.",
                 "examples": ["{\"type\": \"Complements\", \"dimension\": 2}"],
                 "required": ["dimension"],
                 "properties": {

src/FileFormats/MOF/mof.schema.json

@@ -13,7 +13,7 @@ import MathOptInterface as MOI
 # Julia 1.6 removes Grisu from Base. Previously, we went
 #   print_shortest(io, x) = Base.Grisu.print_shortest(io, x)
 # To avoid adding Grisu as a dependency, use the following printing heuristic.
-# TODO(odow): consider printing 1.0 as 1.0 instead of 1, i.e., without the
+# TODO(odow): consider printing 1.0 as 1.0 instead of 1, that is, without the
 # rounding branch.
 function print_shortest(io::IO, x::Real)
     if isinteger(x) && (typemin(Int) <= x <= typemax(Int))
@@ -918,16 +918,12 @@ end
 #            type     name
 #           COLUMNS
 #                     column      row       value     row      value
-#                     name        name                name
 #           RHS
 #                     rhs         row       value     row      value
-#                     name        name                name
 #           RANGES
 #                     range       row       value     row      value
-#                     name        name                name
 #           BOUNDS
 #            type     bound       column    value
-#                     name        name
 #           SOS
 #            type     CaseName    SOSName   SOSpriority
 #                     CaseName    VarName1  VarWeight1
@@ -1028,7 +1024,7 @@ end
     HEADER_INDICATORS,
 )
 
-# Headers(s) gets called _alot_ (on every line), so we try very hard to be
+# `Headers(s)` gets called _alot_ (on every line), so we try very hard to be
 # efficient.
 function Headers(s::AbstractString)
     N = length(s)
@@ -1618,7 +1614,7 @@ function _parse_single_bound(
     elseif bound_type == "FR"
         # So even though FR bounds should be of the form:
         #  FR BOUND1    VARNAME
-        # there are cases in MIPLIB2017 (e.g., leo1 and leo2) like so:
+        # there are cases in MIPLIB2017 (for example, leo1 and leo2) like so:
         #  FR BOUND1    C0000001       .000000
         # In these situations, just ignore the value.
         data.col_lower[col] = -Inf

src/FileFormats/MPS/MPS.jl

@@ -635,7 +635,7 @@ function Base.write(io::IO, model::Model)
 
     # Line 10: common exprs: b,c,o,c1,o1
     # Notes:
-    #  * We don't add common subexpressions (i.e., V blocks).
+    #  * We don't add common subexpressions (that is, V blocks).
     #  * I assume the notation means
     #     - b = in nonlinear objective and constraint
     #     - c = in nonlinear constraint