docs: making use of DocumenterInterLink

Author: franckgaga

docs/Project.toml

@@ -1,19 +1,20 @@
 [deps]
-LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
-Logging = "56ddb016-857b-54e1-b83d-db4d58db5568"
 ControlSystemsBase = "aaaaaaaa-a6ca-5380-bf3e-84a91bcd477e"
 DAQP = "c47d62df-3981-49c8-9651-128b1cd08617"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterInterLinks = "d12716ef-a0f6-4df4-a9f1-a5a34e75c656"
 JuMP = "4076af6c-e467-56ae-b986-b466b2749572"
+LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+Logging = "56ddb016-857b-54e1-b83d-db4d58db5568"
 ModelingToolkit = "961ee093-0014-501f-94e3-6117800e7a78"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
 
 [compat]
-LinearAlgebra = "1.10"
-Logging = "1.10"
 ControlSystemsBase = "1"
+DAQP = "0.6"
 Documenter = "1"
 JuMP = "1"
-DAQP = "0.6"
-Plots = "1"
+LinearAlgebra = "1.10"
+Logging = "1.10"
 ModelingToolkit = "9.50"
+Plots = "1"

docs/make.jl

@@ -3,9 +3,16 @@ ENV["PLOTS_TEST"] = "true"
 ENV["GKSwstype"] = "nul"
 push!(LOAD_PATH,"../src/")
 
-using Documenter
+using Documenter, DocumenterInterLinks
 using ModelPredictiveControl
 
+links = InterLinks(
+    "Julia" => "https://docs.julialang.org/en/v1/objects.inv",
+    "ControlSystemsBase" => "https://juliacontrol.github.io/ControlSystems.jl/stable/objects.inv",
+    "JuMP" => "https://jump.dev/JuMP.jl/stable/objects.inv",
+    "DifferentiationInterface" => "https://juliadiff.org/DifferentiationInterface.jl/DifferentiationInterface/stable/objects.inv",
+)
+
 DocMeta.setdocmeta!(
     ModelPredictiveControl, 
     :DocTestSetup, 
@@ -16,6 +23,7 @@ makedocs(
     sitename    = "ModelPredictiveControl.jl",
     #format = Documenter.LaTeX(platform = "none"),
     doctest     = true,
+    plugins     = [links],
     format      = Documenter.HTML(
         prettyurls = get(ENV, "CI", nothing) == "true",
         edit_link = "main"

src/controller/linmpc.jl

@@ -146,8 +146,8 @@ arguments. This controller allocates memory at each time step for the optimizati
 - `Cwt=1e5` : slack variable weight ``C`` (scalar), use `Cwt=Inf` for hard constraints only.
 - `transcription=SingleShooting()` : a [`TranscriptionMethod`](@ref) for the optimization.
 - `optim=JuMP.Model(OSQP.MathOptInterfaceOSQP.Optimizer)` : quadratic optimizer used in
-  the predictive controller, provided as a [`JuMP.Model`](https://jump.dev/JuMP.jl/stable/api/JuMP/#JuMP.Model)
-  (default to [`OSQP`](https://osqp.org/docs/parsers/jump.html) optimizer).
+  the predictive controller, provided as a [`JuMP.Model`](@extref) object (default to 
+  [`OSQP`](https://osqp.org/docs/parsers/jump.html) optimizer).
 - additional keyword arguments are passed to [`SteadyKalmanFilter`](@ref) constructor.
 
 # Examples

src/controller/nonlinmpc.jl

@@ -194,17 +194,14 @@ This controller allocates memory at each time step for the optimization.
 - `p=model.p` : ``J_E`` and ``\mathbf{g_c}`` functions parameter ``\mathbf{p}`` (any type).
 - `transcription=SingleShooting()` : a [`TranscriptionMethod`](@ref) for the optimization.
 - `optim=JuMP.Model(Ipopt.Optimizer)` : nonlinear optimizer used in the predictive
-   controller, provided as a [`JuMP.Model`](https://jump.dev/JuMP.jl/stable/api/JuMP/#JuMP.Model)
-   (default to [`Ipopt`](https://github.com/jump-dev/Ipopt.jl) optimizer).
+   controller, provided as a [`JuMP.Model`](@extref) object (default to [`Ipopt`](https://github.com/jump-dev/Ipopt.jl) optimizer).
 - `gradient=AutoForwardDiff()` : an `AbstractADType` backend for the gradient of the objective
-   function, see [`DifferentiationInterface`][1].
+   function, see [`DifferentiationInterface`](@extref DifferentiationInterface List).
 - `jacobian=default_jacobian(transcription)` : an `AbstractADType` backend for the Jacobian
    of the nonlinear constraints, see `gradient` above for the options (default in Extended Help).
 - additional keyword arguments are passed to [`UnscentedKalmanFilter`](@ref) constructor 
   (or [`SteadyKalmanFilter`](@ref), for [`LinModel`](@ref)).
 
-[1]: https://juliadiff.org/DifferentiationInterface.jl/DifferentiationInterface/stable/explanation/backends/#List
-
 # Examples
 ```jldoctest
 julia> model = NonLinModel((x,u,_,_)->0.5x+u, (x,_,_)->2x, 10.0, 1, 1, 1, solver=nothing);
@@ -253,7 +250,7 @@ NonLinMPC controller with a sample time Ts = 10.0 s, Ipopt optimizer, UnscentedK
     By default, the optimization relies on dense [`ForwardDiff`](https://github.com/JuliaDiff/ForwardDiff.jl)
     automatic differentiation (AD) to compute the objective and constraint derivatives. One
     exception: if `transcription` is not a [`SingleShooting`](@ref), the `jacobian` argument
-    defaults to this [sparse backend][2]:
+    defaults to this [sparse backend](@extref DifferentiationInterface Sparsity):
     ```julia
         AutoSparse(
             AutoForwardDiff(); 
@@ -262,14 +259,11 @@ NonLinMPC controller with a sample time Ts = 10.0 s, Ipopt optimizer, UnscentedK
         )
     ```
     Optimizers generally benefit from exact derivatives like AD. However, the [`NonLinModel`](@ref) 
-    state-space functions must be compatible with this feature. See `JuMP` [documentation][3]
+    state-space functions must be compatible with this feature. See [`JuMP` documentation](@extref JuMP Common-mistakes-when-writing-a-user-defined-operator)
     for common mistakes when writing these functions.
 
     Note that if `Cwt≠Inf`, the attribute `nlp_scaling_max_gradient` of `Ipopt` is set to 
     `10/Cwt` (if not already set), to scale the small values of ``ϵ``.
-
-    [2]: https://juliadiff.org/DifferentiationInterface.jl/DifferentiationInterface/stable/explanation/advanced/#Sparsity
-    [3]: https://jump.dev/JuMP.jl/stable/manual/nonlinear/#Common-mistakes-when-writing-a-user-defined-operator
 """
 function NonLinMPC(
     model::SimModel;
@@ -581,16 +575,13 @@ This method is really intricate and I'm not proud of it. That's because of 3 ele
 - These functions are used inside the nonlinear optimization, so they must be type-stable
   and as efficient as possible.
 - The `JuMP` NLP syntax forces splatting for the decision variable, which implies use
-  of `Vararg{T,N}` (see the [performance tip][1]) and memoization to avoid redundant
-  computations. This is already complex, but it's even worse knowing that most automatic
-  differentiation tools do not support splatting.
+  of `Vararg{T,N}` (see the [performance tip][@extref Julia Be-aware-of-when-Julia-avoids-specializing]
+  ) and memoization to avoid redundant computations. This is already complex, but it's even
+  worse knowing that most automatic differentiation tools do not support splatting.
 - The signature of gradient and hessian functions is not the same for univariate (`nZ̃ == 1`)
   and multivariate (`nZ̃ > 1`) operators in `JuMP`. Both must be defined.
 
-Inspired from: [User-defined operators with vector outputs][2]
-
-[1]: https://docs.julialang.org/en/v1/manual/performance-tips/#Be-aware-of-when-Julia-avoids-specializing
-[2]: https://jump.dev/JuMP.jl/stable/tutorials/nonlinear/tips_and_tricks/#User-defined-operators-with-vector-outputs
+Inspired from: [User-defined operators with vector outputs](@extref JuMP User-defined-operators-with-vector-outputs)
 """
 function get_optim_functions(
     mpc::NonLinMPC, 

src/estimator/kalman.jl

@@ -80,7 +80,8 @@ end
 
 Construct a steady-state Kalman Filter with the [`LinModel`](@ref) `model`.
 
-The steady-state (or [asymptotic][1]) Kalman filter is based on the process model :
+The steady-state (or [asymptotic](https://en.wikipedia.org/wiki/Kalman_filter#Asymptotic_form))
+Kalman filter is based on the process model:
 ```math
 \begin{aligned}
     \mathbf{x}(k+1) &= 
@@ -124,8 +125,6 @@ state of the next time step ``\mathbf{x̂}_k(k+1)``. This estimator is allocatio
 - `direct=true`: construct with a direct transmission from ``\mathbf{y^m}`` (a.k.a. current
    estimator, in opposition to the delayed/predictor form).
 
-[1]: https://en.wikipedia.org/wiki/Kalman_filter#Asymptotic_form
-
 # Examples
 ```jldoctest
 julia> model = LinModel([tf(3, [30, 1]); tf(-2, [5, 1])], 0.5);
@@ -161,11 +160,9 @@ SteadyKalmanFilter estimator with a sample time Ts = 0.5 s, LinModel and:
     !!! tip
         Increasing `σQint_u` and `σQint_ym` values increases the integral action "gain".
 
-    The constructor pre-compute the steady-state Kalman gain `K̂` with the [`kalman`][2]
+    The constructor pre-compute the steady-state Kalman gain `K̂` with the [`kalman`](@extref ControlSystemsBase.kalman)
     function. It can sometimes fail, for example when `model` matrices are ill-conditioned.
     In such a case, you can try the alternative time-varying [`KalmanFilter`](@ref).
-
-    [2]: https://juliacontrol.github.io/ControlSystems.jl/stable/lib/synthesis/#ControlSystemsBase.kalman-Tuple{Any,%20Any,%20Any,%20Any,%20Any,%20Vararg{Any}}
 """
 function SteadyKalmanFilter(
     model::SM;

src/estimator/luenberger.jl

@@ -77,8 +77,8 @@ Extended Help). The argument `poles` is a vector of `model.nx + sum(nint_u) + su
 elements specifying the observer poles/eigenvalues (near ``z=0.5`` by default). The observer
 is constructed with a direct transmission from ``\mathbf{y^m}`` if `direct=true` (a.k.a. 
 current observers, in opposition to the delayed/prediction form). The method computes the
-observer gain `K̂` with [`place`](https://juliacontrol.github.io/ControlSystems.jl/stable/lib/synthesis/#ControlSystemsBase.place).
-This estimator is allocation-free.
+observer gain `K̂` with [`place`](@extref ControlSystemsBase.place) function. This estimator
+is allocation-free.
 
 # Examples
 ```jldoctest

src/estimator/mhe/construct.jl

@@ -257,18 +257,16 @@ transcription for now.
 - `σPint_ym_0=fill(1,sum(nint_ym))` or *`sigmaPint_ym_0`* : same than `σP_0` but for the unmeasured
     disturbances at measured outputs ``\mathbf{P_{int_{ym}}}(0)`` (composed of integrators).
 - `Cwt=Inf` : slack variable weight ``C``, default to `Inf` meaning hard constraints only.
-- `optim=default_optim_mhe(model)` : a [`JuMP.Model`](https://jump.dev/JuMP.jl/stable/api/JuMP/#JuMP.Model)
-   with a quadratic/nonlinear optimizer for solving (default to [`Ipopt`](https://github.com/jump-dev/Ipopt.jl),
+- `optim=default_optim_mhe(model)` : a [`JuMP.Model`](@extref) object with a quadratic or
+   nonlinear optimizer for solving (default to [`Ipopt`](https://github.com/jump-dev/Ipopt.jl),
    or [`OSQP`](https://osqp.org/docs/parsers/jump.html) if `model` is a [`LinModel`](@ref)).
 - `gradient=AutoForwardDiff()` : an `AbstractADType` backend for the gradient of the objective
-   function if `model` is not a [`LinModel`](@ref), see [`DifferentiationInterface`][1].
+   function if `model` is not a [`LinModel`](@ref), see [`DifferentiationInterface`][@extref DifferentiationInterface List].
 - `jacobian=AutoForwardDiff()` : an `AbstractADType` backend for the Jacobian of the
    constraints if `model` is not a [`LinModel`](@ref), see `gradient` above for the options.
 - `direct=true`: construct with a direct transmission from ``\mathbf{y^m}`` (a.k.a. current
    estimator, in opposition to the delayed/predictor form).
 
-[1]: https://juliadiff.org/DifferentiationInterface.jl/DifferentiationInterface/stable/explanation/backends/#List
-
 # Examples
 ```jldoctest
 julia> model = NonLinModel((x,u,_,_)->0.1x+u, (x,_,_)->2x, 10.0, 1, 1, 1, solver=nothing);
@@ -348,11 +346,9 @@ MovingHorizonEstimator estimator with a sample time Ts = 10.0 s, Ipopt optimizer
       default, a [`KalmanFilter`](@ref) estimates the arrival covariance (customizable).
     - Else, a nonlinear program with automatic differentiation (AD) solves the optimization.
       Optimizers generally benefit from exact derivatives like AD. However, the `f` and `h` 
-      functions must be compatible with this feature. See the `JuMP` [documentation][3]
+      functions must be compatible with this feature. See the [`JuMP` documentation](@extref JuMP Common-mistakes-when-writing-a-user-defined-operator)
       for common mistakes when writing these functions. An [`UnscentedKalmanFilter`](@ref)
       estimates the arrival covariance by default.
-
-    [3]: https://jump.dev/JuMP.jl/stable/manual/nonlinear/#Common-mistakes-when-writing-a-user-defined-operator
     
     The slack variable ``ϵ`` relaxes the constraints if enabled, see [`setconstraint!`](@ref). 
     It is disabled by default for the MHE (from `Cwt=Inf`) but it should be activated for

src/model/linearization.jl

@@ -131,10 +131,8 @@ julia> linmodel.A
     equations are similar if the nonlinear model has nonzero operating points.
 
     Automatic differentiation (AD) allows exact Jacobians. The [`NonLinModel`](@ref) `f` and
-    `h` functions must be compatible with this feature though. See `JuMP` [documentation][3]
+    `h` functions must be compatible with this feature though. See [`JuMP` documentation][@extref JuMP Common-mistakes-when-writing-a-user-defined-operator]
     for common mistakes when writing these functions.
-
-    [3]: https://jump.dev/JuMP.jl/stable/manual/nonlinear/#Common-mistakes-when-writing-a-user-defined-operator
 """
 function linearize(model::SimModel{NT}; kwargs...) where NT<:Real
     nu, nx, ny, nd = model.nu, model.nx, model.ny, model.nd

src/model/linmodel.jl

@@ -84,7 +84,7 @@ resamples discrete ones if `Ts ≠ sys.Ts`, computes a new realization if not mi
 separates the ``\mathbf{z}`` terms in two parts (details in Extended Help). The rest of the
 documentation assumes discrete dynamics since all systems end up in this form.
 
-See also [`ss`](https://juliacontrol.github.io/ControlSystems.jl/stable/lib/constructors/#ControlSystemsBase.ss)
+See also [`ss`](@extref ControlSystemsBase.ss)
 
 # Examples
 ```jldoctest
@@ -112,12 +112,12 @@ LinModel with a sample time Ts = 0.1 s and:
         \mathbf{y}(k)   &=  \mathbf{C x}(k) + \mathbf{D z}(k)
     \end{aligned}
     ```
-    Continuous dynamics are internally discretized using [`c2d`][1] and `:zoh` for
-    manipulated inputs, and `:tustin`, for measured disturbances. Lastly, if `sys` is
-    discrete and the provided argument `Ts ≠ sys.Ts`, the system is resampled by using the
-    aforementioned discretization methods.
+    Continuous dynamics are internally discretized using [`c2d`](@extref ControlSystemsBase.c2d)
+    and `:zoh` for manipulated inputs, and `:tustin`, for measured disturbances. Lastly, if
+    `sys` is discrete and the provided argument `Ts ≠ sys.Ts`, the system is resampled by
+    using the aforementioned discretization methods.
 
-    Note that the constructor transforms the system to its minimal realization using [`minreal`][2]
+    Note that the constructor transforms the system to its minimal realization using [`minreal`](@extref ControlSystemsBase.minreal)
     for controllability/observability. As a consequence, the final state-space
     representation may be different from the one provided in `sys`. It is also converted 
     into a more practical form (``\mathbf{D_u=0}`` because of the zero-order hold):
@@ -129,9 +129,6 @@ LinModel with a sample time Ts = 0.1 s and:
     ```
     Use the syntax [`LinModel{NT}(A, Bu, C, Bd, Dd, Ts)`](@ref) to force a specific
     state-space representation.
-
-    [1]: https://juliacontrol.github.io/ControlSystems.jl/stable/lib/constructors/#ControlSystemsBase.c2d
-    [2]: https://juliacontrol.github.io/ControlSystems.jl/stable/lib/constructors/#ControlSystemsBase.minreal
 """
 function LinModel(
     sys::StateSpace{E, NT},
@@ -195,7 +192,7 @@ Convert to minimal realization state-space when `sys` is a transfer function.
 `sys` is equal to ``\frac{\mathbf{y}(s)}{\mathbf{z}(s)}`` for continuous-time, and 
 ``\frac{\mathbf{y}(z)}{\mathbf{z}(z)}``, for discrete-time.
 
-See also [`tf`](https://juliacontrol.github.io/ControlSystems.jl/stable/lib/constructors/#ControlSystemsBase.tf)
+See also [`tf`](@extref ControlSystemsBase.tf)
 
 # Examples
 ```jldoctest