docs is generated ok

Author: ocots

docs/docutils/DocumenterReference.jl

@@ -2,11 +2,42 @@
 
 The `CTModels.jl` package is part of the [control-toolbox ecosystem](https://github.com/control-toolbox).
 
-The root package is [OptimalControl.jl](https://github.com/control-toolbox/OptimalControl.jl) which aims to provide tools to model and solve optimal control problems with ordinary differential equations by direct and indirect methods, both on CPU and GPU.
+!!! note
 
-**API Documentation**
+    The root package is [OptimalControl.jl](https://github.com/control-toolbox/OptimalControl.jl) which aims to provide tools to model and solve optimal control problems with ordinary differential equations by direct and indirect methods, both on CPU and GPU.
 
-```@contents
-Pages = Main.API_PAGES
-Depth = 1
-```
+!!! warning
+
+    In some examples in the documentation, private methods are shown without the module
+    prefix. This is done for the sake of clarity and readability.
+
+    ```julia-repl
+    julia> using CTModels
+    julia> x = 1
+    julia> private_fun(x) # throws an error
+    ```
+
+    This should instead be written as:
+
+    ```julia-repl
+    julia> using CTModels
+    julia> x = 1
+    julia> CTModels.private_fun(x)
+    ```
+
+    If the method is re-exported by another package, 
+    
+    ```julia
+    module OptimalControl
+        import CTModels: private_fun
+        export private_fun
+    end
+    ```
+    
+    then there is no need to prefix it with the original module name:
+
+    ```julia-repl
+    julia> using OptimalControl
+    julia> x = 1
+    julia> private_fun(x)
+    ```

docs/make.jl

@@ -10,7 +10,7 @@ Modelers implement the
 [`AbstractOptimizationModeler`](@ref CTModels.AbstractOptimizationModeler)
 interface and are also
 [`AbstractOCPTool`](@ref CTModels.AbstractOCPTool)s. This means they follow
-both the options interface (see [`ocp_tools.md`](@ref)) and a calling
+both the options interface (see [OCP Tools](ocp_tools.md)) and a calling
 interface specific to optimization problems.
 
 ## Overview of the contract
@@ -54,7 +54,7 @@ not specialized.
 
 Because `AbstractOptimizationModeler <: AbstractOCPTool`, modelers follow the
 same options pattern as other tools. See
-[`ocp_tools.md`](@ref) for a detailed discussion.
+[OCP Tools](ocp_tools.md) for a detailed discussion.
 
 In short, a typical modeler definition looks like:
 
@@ -148,5 +148,5 @@ To integrate a new modeler into such a registry, you typically:
    [`tool_package_name`](@ref CTModels.tool_package_name).
 3. Add the modeler type to the appropriate `REGISTERED_*` constant.
 
-See also the `ocp_tools.md` page for the generic `AbstractOCPTool` interface
+See also the [OCP Tools](ocp_tools.md) page for the generic `AbstractOCPTool` interface
 and examples such as `ADNLPModeler` and `ExaModeler`.

docs/src/index.md

@@ -122,4 +122,4 @@ A typical workflow is:
    to turn the back-end solution into an OCP-related representation.
 
 For the implementation of modelers and tools, see also
-[`ocp_tools.md`](@ref) and the separate page on optimization modelers.
+[OCP Tools](ocp_tools.md) and the separate page on optimization modelers.

docs/src/interfaces/optimization_modelers.md

@@ -55,7 +55,7 @@ Type alias for a time.
 julia> const Time = ctNumber
 ```
 
-See also: [`ctNumber`](@ref), [`Times`](@ref), [`TimesDisc`](@ref).
+See also: [`ctNumber`](@ref), [`Times`](@ref CTModels.Times), [`TimesDisc`](@ref).
 """
 const Time = ctNumber
 
@@ -88,7 +88,7 @@ Type alias for a grid of times. This is used to define a discretization of time
 julia> const TimesDisc = Union{Times, StepRangeLen}
 ```
 
-See also: [`Time`](@ref), [`Times`](@ref).
+See also: [`Time`](@ref), [`Times`](@ref CTModels.Times).
 """
 const TimesDisc = Union{Times,StepRangeLen}
 
@@ -99,7 +99,7 @@ Type alias for a dictionary of constraints. This is used to store constraints be
 julia> const TimesDisc = Union{Times, StepRangeLen}
 ```
 
-See also: [`ConstraintsModel`](@ref), [`PreModel`](@ref) and [`Model`](@ref).
+See also: [`ConstraintsModel`](@ref), [`PreModel`](@ref) and [`Model`](@ref CTModels.Model).
 """
 const ConstraintsDictType = OrderedDict{
     Symbol,Tuple{Symbol,Union{Function,OrdinalRange{<:Int}},ctVector,ctVector}
@@ -136,82 +136,42 @@ struct JSON3Tag <: AbstractTag end
 
 # -----------------------------
 # to be extended
-"""
-$(TYPEDSIGNATURES)
-
-Plot an optimal control solution.
-
-This method requires the Plots extension to be loaded.
-Throws `CTBase.ExtensionError` if Plots is not available.
-"""
 function RecipesBase.plot(sol::AbstractSolution, description::Symbol...; kwargs...)
     throw(CTBase.ExtensionError(:Plots))
 end
 
-"""
-$(TYPEDSIGNATURES)
-
-Export an optimal control solution to a JLD2 file.
-
-This method requires the JLD2 extension to be loaded.
-Throws `CTBase.ExtensionError` if JLD2 is not available.
-"""
 function export_ocp_solution(::JLD2Tag, ::AbstractSolution; filename::String)
     throw(CTBase.ExtensionError(:JLD2))
 end
 
-"""
-$(TYPEDSIGNATURES)
-
-Import an optimal control solution from a JLD2 file.
-
-This method requires the JLD2 extension to be loaded.
-Throws `CTBase.ExtensionError` if JLD2 is not available.
-"""
 function import_ocp_solution(::JLD2Tag, ::AbstractModel; filename::String)
     throw(CTBase.ExtensionError(:JLD2))
 end
 
-"""
-$(TYPEDSIGNATURES)
-
-Export an optimal control solution to a JSON file.
-
-This method requires the JSON3 extension to be loaded.
-Throws `CTBase.ExtensionError` if JSON3 is not available.
-"""
 function export_ocp_solution(::JSON3Tag, ::AbstractSolution; filename::String)
     throw(CTBase.ExtensionError(:JSON3))
 end
 
-"""
-$(TYPEDSIGNATURES)
-
-Import an optimal control solution from a JSON file.
-
-This method requires the JSON3 extension to be loaded.
-Throws `CTBase.ExtensionError` if JSON3 is not available.
-"""
 function import_ocp_solution(::JSON3Tag, ::AbstractModel; filename::String)
     throw(CTBase.ExtensionError(:JSON3))
 end
 
 """
-$(TYPEDSIGNATURES)
+    export_ocp_solution(sol; format=:JLD, filename="solution")
 
-Export a solution in JLD or JSON formats. Redirect to one of the methods:
+Export an optimal control solution to a file.
 
-- [`export_ocp_solution(JLD2Tag(), sol, filename=filename)`](@ref export_ocp_solution(::CTModels.JLD2Tag, ::CTModels.Solution))
-- [`export_ocp_solution(JSON3Tag(), sol, filename=filename)`](@ref export_ocp_solution(::CTModels.JSON3Tag, ::CTModels.Solution))
+# Arguments
+- `sol::AbstractSolution`: The solution to export.
 
-# Examples
+# Keyword Arguments
+- `format::Symbol=:JLD`: Export format, either `:JLD` or `:JSON`.
+- `filename::String="solution"`: Base filename (extension added automatically).
 
-```julia-repl
-julia> using JSON3
-julia> export_ocp_solution(sol; filename="solution", format=:JSON)
-julia> using JLD2
-julia> export_ocp_solution(sol; filename="solution", format=:JLD)  # JLD is the default
-```
+# Notes
+Requires loading the appropriate package (`JLD2` or `JSON3`) before use.
+
+See also: [`import_ocp_solution`](@ref)
 """
 function export_ocp_solution(
     sol::AbstractSolution;
@@ -232,21 +192,24 @@ function export_ocp_solution(
 end
 
 """
-$(TYPEDSIGNATURES)
+    import_ocp_solution(ocp; format=:JLD, filename="solution")
 
-Import a solution from a JLD or JSON file. Redirect to one of the methods:
+Import an optimal control solution from a file.
 
-- [`import_ocp_solution(JLD2Tag(), ocp, filename=filename)`](@ref import_ocp_solution(::CTModels.JLD2Tag, ::CTModels.Model))
-- [`import_ocp_solution(JSON3Tag(), ocp, filename=filename)`](@ref import_ocp_solution(::CTModels.JSON3Tag, ::CTModels.Model))
+# Arguments
+- `ocp::AbstractModel`: The model associated with the solution.
 
-# Examples
+# Keyword Arguments
+- `format::Symbol=:JLD`: Import format, either `:JLD` or `:JSON`.
+- `filename::String="solution"`: Base filename (extension added automatically).
 
-```julia-repl
-julia> using JSON3
-julia> sol = import_ocp_solution(ocp; filename="solution", format=:JSON)
-julia> using JLD2
-julia> sol = import_ocp_solution(ocp; filename="solution", format=:JLD)  # JLD is the default
-```
+# Returns
+- `Solution`: The imported solution.
+
+# Notes
+Requires loading the appropriate package (`JLD2` or `JSON3`) before use.
+
+See also: [`export_ocp_solution`](@ref)
 """
 function import_ocp_solution(
     ocp::AbstractModel;
@@ -303,7 +266,4 @@ include(joinpath(@__DIR__, "nlp", "discretized_ocp.jl"))
 include(joinpath(@__DIR__, "nlp", "model_api.jl"))
 include(joinpath(@__DIR__, "init", "initial_guess.jl"))
 
-#
-export plot, plot!
-
 end

docs/src/interfaces/optimization_problems.md

@@ -20,7 +20,7 @@ Concrete subtypes `T <: AbstractOCPTool` are expected to:
   - `options_sources::NamedTuple` — provenance for each option
     (`:ct_default` or `:user`).
 - optionally provide option metadata by specializing
-  [`_option_specs(::Type{T})`](@ref), returning a `NamedTuple` of
+  [`_option_specs`](@ref CTModels._option_specs), returning a `NamedTuple` of
   [`OptionSpec`](@ref) values.
 - typically define a keyword-only constructor
   `T(; kwargs...)` implemented using [`_build_ocp_tool_options`](@ref), so
@@ -54,19 +54,6 @@ struct OptionSpec
     description::Any  # Short English description (String) or `missing` if not documented yet.
 end
 
-"""
-$(TYPEDSIGNATURES)
-
-Construct an [`OptionSpec`](@ref) with keyword arguments.
-
-# Keyword Arguments
-
-- `type`: Expected Julia type for the option value (default: `missing`).
-- `default`: Default value (default: `missing`).
-- `description`: Human-readable description (default: `missing`).
-"""
-OptionSpec(; type=missing, default=missing, description=missing) = OptionSpec(type, default, description)
-
 """
 $(TYPEDEF)
 

src/CTModels.jl

@@ -6,10 +6,10 @@ $(TYPEDEF)
 
 Abstract base type for optimal control problem models.
 
-Subtypes represent either a fully built immutable model ([`Model`](@ref)) or a
+Subtypes represent either a fully built immutable model ([`Model`](@ref CTModels.Model)) or a
 mutable model under construction ([`PreModel`](@ref)).
 
-See also: [`Model`](@ref), [`PreModel`](@ref).
+See also: [`Model`](@ref CTModels.Model), [`PreModel`](@ref).
 """
 abstract type AbstractModel end
 
@@ -102,49 +102,49 @@ end
 """
 $(TYPEDSIGNATURES)
 
-Return `true` since times are always set in a built [`Model`](@ref).
+Return `true` since times are always set in a built [`Model`](@ref CTModels.Model).
 """
 __is_times_set(ocp::Model)::Bool = true
 
 """
 $(TYPEDSIGNATURES)
 
-Return `true` since state is always set in a built [`Model`](@ref).
+Return `true` since state is always set in a built [`Model`](@ref CTModels.Model).
 """
 __is_state_set(ocp::Model)::Bool = true
 
 """
 $(TYPEDSIGNATURES)
 
-Return `true` since control is always set in a built [`Model`](@ref).
+Return `true` since control is always set in a built [`Model`](@ref CTModels.Model).
 """
 __is_control_set(ocp::Model)::Bool = true
 
 """
 $(TYPEDSIGNATURES)
 
-Return `true` since variable is always set in a built [`Model`](@ref).
+Return `true` since variable is always set in a built [`Model`](@ref CTModels.Model).
 """
 __is_variable_set(ocp::Model)::Bool = true
 
 """
 $(TYPEDSIGNATURES)
 
-Return `true` since dynamics is always set in a built [`Model`](@ref).
+Return `true` since dynamics is always set in a built [`Model`](@ref CTModels.Model).
 """
 __is_dynamics_set(ocp::Model)::Bool = true
 
 """
 $(TYPEDSIGNATURES)
 
-Return `true` since objective is always set in a built [`Model`](@ref).
+Return `true` since objective is always set in a built [`Model`](@ref CTModels.Model).
 """
 __is_objective_set(ocp::Model)::Bool = true
 
 """
 $(TYPEDSIGNATURES)
 
-Return `true` since definition is always set in a built [`Model`](@ref).
+Return `true` since definition is always set in a built [`Model`](@ref CTModels.Model).
 """
 __is_definition_set(ocp::Model)::Bool = true
 
@@ -154,7 +154,7 @@ $(TYPEDEF)
 Mutable optimal control problem model under construction.
 
 A `PreModel` is used to incrementally define an optimal control problem before
-building it into an immutable [`Model`](@ref). Fields can be set in any order
+building it into an immutable [`Model`](@ref CTModels.Model). Fields can be set in any order
 and the model is validated before building.
 
 # Fields

src/core/types/nlp.jl

@@ -40,7 +40,7 @@ Return the original optimal control problem from a discretised problem.
 
 # Returns
 
-- The underlying [`Model`](@ref) (optimal control problem).
+- The underlying [`Model`](@ref CTModels.Model) (optimal control problem).
 """
 function ocp_model(prob::DiscretizedOptimalControlProblem)
     return prob.optimal_control_problem

src/core/types/ocp_model.jl

@@ -63,6 +63,10 @@ end
 #   - description : short human-readable description (or `missing`).
 # ---------------------------------------------------------------------------
 
+function OptionSpec(; type=missing, default=missing, description=missing)
+    OptionSpec(type, default, description)
+end
+
 # Default: no metadata for a given tool type.
 """
 $(TYPEDSIGNATURES)