Merge pull request #465 from control-toolbox/462-bug-link-broken-in-doc

up doc

Author: ocots

docs/make.jl

@@ -31,24 +31,24 @@ makedocs(;
         ],
     ),
     pages=[
-        "Introduction" => "index.md",
-        "Basic examples" => [
+        "Getting Started" => "index.md",
+        "Basic Examples" => [
             "Energy minimisation" => "tutorial-double-integrator-energy.md",
             "Time mininimisation" => "tutorial-double-integrator-time.md",
         ],
         "Manual" => [
-            "Abstract syntax" => "tutorial-abstract.md",
-            "Initial guess" => "tutorial-initial-guess.md",
-            "Solve" => "tutorial-solve.md",
+            "Define a problem" => "tutorial-abstract.md",
+            "Set an initial guess" => "tutorial-initial-guess.md",
+            "Solve a problem" => "tutorial-solve.md",
             "Plot a solution" => "tutorial-plot.md",
-            "Flow" => "tutorial-flow.md",
+            "Compute flows" => "tutorial-flow.md",
         ],
-        "Tutorials" => [
-            "Discretisation options" => "tutorial-discretisation.md",
+        "Tutorials and Advanced Features" => [
             "Discrete continuation" => "tutorial-continuation.md",
-            "NLP options" => "tutorial-nlp.md",
-            "Goddard: direct, indirect" => "tutorial-goddard.md",
+            "Discretisation options" => "tutorial-discretisation.md",
+            "NLP manipulations" => "tutorial-nlp.md",
             "Indirect simple shooting" => "tutorial-iss.md",
+            "Goddard: direct, indirect" => "tutorial-goddard.md",
             "Linear–quadratic regulator" => "tutorial-lqr-basic.md",
             "Minimal action" => "tutorial-mam.md",
         ],

docs/src/dev-ctbase.md

@@ -1,19 +1,19 @@
 # CTBase.jl
 
 ```@meta
-CollapsedDocStrings = true
+CollapsedDocStrings = false
 ```
 
 The [CTBase.jl](control-toolbox.org/CTBase.jl/) package is part of the [control-toolbox ecosystem](https://github.com/control-toolbox).
 
 ```mermaid
 flowchart TD
-B(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctbase.html'>CTBase</a>)
-M(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctmodels.html'>CTModels</a>)
-P(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctparser.html'>CTParser</a>)
-O(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-optimalcontrol.html'>OptimalControl</a>)
-D(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctdirect.html'>CTDirect</a>)
-F(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctflows.html'>CTFlows</a>)
+B(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctbase.html'>CTBase</a>)
+M(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctmodels.html'>CTModels</a>)
+P(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctparser.html'>CTParser</a>)
+O(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-optimalcontrol.html'>OptimalControl</a>)
+D(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctdirect.html'>CTDirect</a>)
+F(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctflows.html'>CTFlows</a>)
 O --> D
 O --> M
 O --> F

docs/src/dev-ctdirect.md

@@ -1,19 +1,19 @@
 # CTDirect.jl
 
 ```@meta
-CollapsedDocStrings = true
+CollapsedDocStrings = false
 ```
 
 The [CTDirect.jl](control-toolbox.org/CTDirect.jl) package is part of the [control-toolbox ecosystem](https://github.com/control-toolbox).
 
 ```mermaid
 flowchart TD
-B(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctbase.html'>CTBase</a>)
-M(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctmodels.html'>CTModels</a>)
-P(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctparser.html'>CTParser</a>)
-O(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-optimalcontrol.html'>OptimalControl</a>)
-D(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctdirect.html'>CTDirect</a>)
-F(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctflows.html'>CTFlows</a>)
+B(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctbase.html'>CTBase</a>)
+M(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctmodels.html'>CTModels</a>)
+P(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctparser.html'>CTParser</a>)
+O(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-optimalcontrol.html'>OptimalControl</a>)
+D(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctdirect.html'>CTDirect</a>)
+F(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctflows.html'>CTFlows</a>)
 O --> D
 O --> M
 O --> F

docs/src/dev-ctflows.md

@@ -1,19 +1,19 @@
 # CTFlows.jl
 
 ```@meta
-CollapsedDocStrings = true
+CollapsedDocStrings = false
 ```
 
 The [CTFlows.jl](control-toolbox.org/CTFlows.jl) package is part of the [control-toolbox ecosystem](https://github.com/control-toolbox).
 
 ```mermaid
 flowchart TD
-B(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctbase.html'>CTBase</a>)
-M(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctmodels.html'>CTModels</a>)
-P(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctparser.html'>CTParser</a>)
-O(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-optimalcontrol.html'>OptimalControl</a>)
-D(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctdirect.html'>CTDirect</a>)
-F(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctflows.html'>CTFlows</a>)
+B(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctbase.html'>CTBase</a>)
+M(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctmodels.html'>CTModels</a>)
+P(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctparser.html'>CTParser</a>)
+O(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-optimalcontrol.html'>OptimalControl</a>)
+D(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctdirect.html'>CTDirect</a>)
+F(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctflows.html'>CTFlows</a>)
 O --> D
 O --> M
 O --> F

docs/src/dev-ctmodels.md

@@ -1,19 +1,19 @@
 # CTModels.jl
 
 ```@meta
-CollapsedDocStrings = true
+CollapsedDocStrings = false
 ```
 
 The [CTModels.jl](control-toolbox.org/CTModels.jl) package is part of the [control-toolbox ecosystem](https://github.com/control-toolbox).
 
 ```mermaid
 flowchart TD
-B(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctbase.html'>CTBase</a>)
-M(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctmodels.html'>CTModels</a>)
-P(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctparser.html'>CTParser</a>)
-O(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-optimalcontrol.html'>OptimalControl</a>)
-D(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctdirect.html'>CTDirect</a>)
-F(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctflows.html'>CTFlows</a>)
+B(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctbase.html'>CTBase</a>)
+M(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctmodels.html'>CTModels</a>)
+P(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctparser.html'>CTParser</a>)
+O(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-optimalcontrol.html'>OptimalControl</a>)
+D(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctdirect.html'>CTDirect</a>)
+F(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctflows.html'>CTFlows</a>)
 O --> D
 O --> M
 O --> F

docs/src/dev-ctparser.md

@@ -1,19 +1,19 @@
 # CTParser.jl
 
 ```@meta
-CollapsedDocStrings = true
+CollapsedDocStrings = false
 ```
 
 The [CTParser.jl](control-toolbox.org/CTParser.jl) package is part of the [control-toolbox ecosystem](https://github.com/control-toolbox).
 
 ```mermaid
 flowchart TD
-B(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctbase.html'>CTBase</a>)
-M(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctmodels.html'>CTModels</a>)
-P(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctparser.html'>CTParser</a>)
-O(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-optimalcontrol.html'>OptimalControl</a>)
-D(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctdirect.html'>CTDirect</a>)
-F(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctflows.html'>CTFlows</a>)
+B(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctbase.html'>CTBase</a>)
+M(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctmodels.html'>CTModels</a>)
+P(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctparser.html'>CTParser</a>)
+O(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-optimalcontrol.html'>OptimalControl</a>)
+D(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctdirect.html'>CTDirect</a>)
+F(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctflows.html'>CTFlows</a>)
 O --> D
 O --> M
 O --> F

docs/src/dev-optimalcontrol.md

@@ -1,19 +1,19 @@
 # OptimalControl.jl
 
 ```@meta
-CollapsedDocStrings = true
+CollapsedDocStrings = false
 ```
 
 The [OptimalControl.jl](https://control-toolbox.org/OptimalControl.jl) package is part of the [control-toolbox ecosystem](https://github.com/control-toolbox).
 
 ```mermaid
 flowchart TD
-B(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctbase.html'>CTBase</a>)
-M(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctmodels.html'>CTModels</a>)
-P(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctparser.html'>CTParser</a>)
-O(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-optimalcontrol.html'>OptimalControl</a>)
-D(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctdirect.html'>CTDirect</a>)
-F(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctflows.html'>CTFlows</a>)
+B(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctbase.html'>CTBase</a>)
+M(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctmodels.html'>CTModels</a>)
+P(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctparser.html'>CTParser</a>)
+O(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-optimalcontrol.html'>OptimalControl</a>)
+D(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctdirect.html'>CTDirect</a>)
+F(<a href='https://control-toolbox.org/OptimalControl.jl/stable/dev-ctflows.html'>CTFlows</a>)
 O --> D
 O --> M
 O --> F

docs/src/index.md

@@ -4,44 +4,15 @@
 CurrentModule =  OptimalControl
 ```
 
-The OptimalControl.jl package is the root package of the [control-toolbox ecosystem](https://github.com/control-toolbox).
-The control-toolbox ecosystem gathers Julia packages for mathematical control and applications. It aims to provide tools to model and solve optimal control problems with ordinary differential equations by direct and indirect methods.
+The OptimalControl.jl package is the root package of the [control-toolbox ecosystem](https://github.com/control-toolbox). The control-toolbox ecosystem gathers Julia packages for mathematical control and applications. It aims to provide tools to model and solve optimal control problems with ordinary differential equations by direct and indirect methods.
 
 ## Installation
 
-To install OptimalControl.jl please 
-[open Julia's interactive session (known as REPL)](https://docs.julialang.org/en/v1/manual/getting-started)
-and press `]` key in the REPL to use the package mode, then add the package:
+To install OptimalControl.jl, please [open Julia's interactive session (known as REPL)](https://docs.julialang.org/en/v1/manual/getting-started) and use the Julia package manager:
 
 ```julia
-julia> ]
-pkg> add OptimalControl
-```
-
-## Mathematical problem
-
-A (nonautonomous) optimal control problem with possibly free initial and final times can be described as minimising the cost functional
-
-```math
-g(t_0, x(t_0), t_f, x(t_f)) + \int_{t_0}^{t_f} f^{0}(t, x(t), u(t))~\mathrm{d}t
-```
-
-where the state $x$ and the control $u$ are functions subject, for $t \in [t_0, t_f]$,
-to the differential constraint
-
-```math
-   \dot{x}(t) = f(t, x(t), u(t))
-```
-
-and other constraints such as
-
-```math
-\begin{array}{llcll}
-~\xi_l  &\le& \xi(t, u(t))        &\le& \xi_u, \\
-\eta_l &\le& \eta(t, x(t))       &\le& \eta_u, \\
-\psi_l &\le& \psi(t, x(t), u(t)) &\le& \psi_u, \\
-\phi_l &\le& \phi(t_0, x(t_0), t_f, x(t_f)) &\le& \phi_u.
-\end{array}
+using Pkg
+Pkg.add("OptimalControl")
 ```
 
 ## Basic usage
@@ -68,9 +39,10 @@ sol = solve(ocp)
 plot(sol)
 ```
 
-For more details about this problem, please check the [basic example tutorial](@ref tutorial-double-integrator-energy).
-For a comprehensive introduction to the syntax used above to describe the optimal control problem, check the [abstract syntax tutorial](@ref tutorial-abstract).
-The solve options are described in the [solve tutorial](@ref tutorial-solve).
+- For more details about this problem, please check the [basic example tutorial](@ref tutorial-double-integrator-energy). 
+- For a comprehensive introduction to the syntax used above to describe the optimal control problem, check the [abstract syntax tutorial](@ref tutorial-abstract-syntax). 
+- The `solve` function has options, see the [solve tutorial](@ref tutorial-solve).
+- You can customise the plot with the `plot` function, see the [plot tutorial](@ref tutorial-plot).
 
 ## Citing us
 
@@ -92,13 +64,9 @@ url = {https://control-toolbox.org/OptimalControl.jl}
 
 ## Contributing
 
-If you think you found a bug or if you have a feature request / suggestion, feel free to open an 
-[issue](https://github.com/control-toolbox/OptimalControl.jl/issues).
-Before opening a pull request, please start an issue or a discussion on the topic. 
+If you think you found a bug or if you have a feature request / suggestion, feel free to open an [issue](https://github.com/control-toolbox/OptimalControl.jl/issues). Before opening a pull request, please start an issue or a discussion on the topic. 
 
-Contributions are welcomed, check out [how to contribute to a Github project](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project). 
-If it is your first contribution, you can also check [this first contribution tutorial](https://github.com/firstcontributions/first-contributions).
-You can find first good issues (if any 🙂) [here](https://github.com/control-toolbox/OptimalControl.jl/contribute). You may find other packages to contribute to at the [control-toolbox organization](https://github.com/control-toolbox).
+Contributions are welcomed, check out [how to contribute to a Github project](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project). If it is your first contribution, you can also check [this first contribution tutorial](https://github.com/firstcontributions/first-contributions). You can find first good issues (if any 🙂) [here](https://github.com/control-toolbox/OptimalControl.jl/contribute). You may find other packages to contribute to at the [control-toolbox organization](https://github.com/control-toolbox).
 
 If you want to ask a question, feel free to start a discussion [here](https://github.com/orgs/control-toolbox/discussions). This forum is for general discussion about this repository and the [control-toolbox organization](https://github.com/control-toolbox).
 

docs/src/tutorial-abstract.md

@@ -1,4 +1,4 @@
-# [The abstract syntax to define an optimal control problem](@id tutorial-abstract)
+# [The syntax to define an optimal control problem](@id tutorial-abstract-syntax)
 
 The full grammar of [OptimalControl.jl](https://control-toolbox.org/OptimalControl.jl) small *Domain Specific Language* is given below. The idea is to use a syntax that is
 - pure Julia (and, as such, effortlessly analysed by the standard Julia parser),

docs/src/tutorial-double-integrator-energy.md

@@ -1,4 +1,4 @@
-# [Double integrator: energy min (abstract syntax)](@id tutorial-double-integrator-energy)
+# [Double integrator: energy min](@id tutorial-double-integrator-energy)
 
 Let us consider a wagon moving along a rail, whom acceleration can be controlled by a force $u$.
 We denote by $x = (x_1, x_2)$ the state of the wagon, that is its position $x_1$ and its velocity $x_2$.
@@ -51,7 +51,7 @@ nothing # hide
 
 !!! note "Nota bene"
 
-    For a comprehensive introduction to the syntax used above to describe the optimal control problem, check [this abstract syntax tutorial](@ref abstract). In particular, there are non-unicode alternatives for derivatives, integrals, *etc.*
+    For a comprehensive introduction to the syntax used above to define the optimal control problem, check [this abstract syntax tutorial](@ref tutorial-abstract-syntax). In particular, there are non-unicode alternatives for derivatives, integrals, *etc.*
 
 ## [Solve and plot](@id basic-solve-plot)
 
@@ -68,6 +68,10 @@ And plot the solution with:
 plot(sol)
 ```
 
+!!! note "Nota bene"
+
+    The `solve` function has options, see the [solve tutorial](@ref tutorial-solve). You can customise the plot with the `plot` function, see the [plot tutorial](@ref tutorial-plot).
+
 ## State constraint
 
 We add the path constraint
@@ -76,6 +80,8 @@ We add the path constraint
 x_2(t) \le 1.2.
 ```
 
+Let us model, solve and plot the optimal control problem with this constraint.
+
 ```@example main
 ocp = @def begin
 
@@ -95,28 +101,40 @@ ocp = @def begin
 end
 
 sol = solve(ocp)
+
 plot(sol)
 ```
 
-## Save and load
+## Exporting and importing the solution
+
+We can export (or save) the solution in a Julia `.jld2` data file and reload it later, and also export a discretised version of the solution in a more portable [JSON](https://en.wikipedia.org/wiki/JSON) format. Note that the optimal control problem is needed when loading a solution.
 
-We can save the solution in a Julia `.jld2` data file and reload it later, and also export a discretised version of the solution in a more portable [JSON](https://en.wikipedia.org/wiki/JSON) format. Note that the OCP is needed when loading a solution.
+### JLD2
 
 ```@example main
-# load additional modules
-using JLD2, JSON3
+using JLD2
 
-# JLD save / load
 using Suppressor # hide
 @suppress_err begin # hide
 export_ocp_solution(sol; filename_prefix="my_solution")
 end # hide
-sol_reloaded = import_ocp_solution(ocp; filename_prefix="my_solution")
-println("Objective from loaded solution: ", sol_reloaded.objective)
 
-# JSON export / read
+sol_jld = import_ocp_solution(ocp; filename_prefix="my_solution")
+
+println("Objective from computed solution: ", objective(sol))
+println("Objective from imported solution: ", objective(sol_jld))
+```
+
+### JSON
+
+```@example main
+# load additional modules
+using JSON3
+
 export_ocp_solution(sol; filename_prefix="my_solution", format=:JSON)
+
 sol_json = import_ocp_solution(ocp; filename_prefix="my_solution", format=:JSON)
-println("Objective from JSON discrete solution: ", sol_json.objective)
-```
 
+println("Objective from computed solution: ", objective(sol))
+println("Objective from imported solution: ", objective(sol_json))
+```

docs/src/tutorial-double-integrator-time.md

@@ -1,4 +1,4 @@
-# [Double integrator: time minimisation (abstract syntax)](@id double-integrator-time)
+# [Double integrator: time minimisation](@id double-integrator-time)
 
 The problem consists in minimising the final time $t_f$ for the double integrator system
 
@@ -70,7 +70,7 @@ nothing # hide
 
 !!! note "Nota bene"
 
-    For a comprehensive introduction to the syntax used above to describe the optimal control problem, check [this abstract syntax tutorial](@ref abstract). In particular, there are non-unicode alternatives for derivatives, integrals, *etc.*
+    For a comprehensive introduction to the syntax used above to define the optimal control problem, check [this abstract syntax tutorial](@ref tutorial-abstract-syntax). In particular, there are non-unicode alternatives for derivatives, integrals, *etc.*
 
 ## Solve and plot
 
@@ -86,3 +86,7 @@ and plot the solution
 ```@example main
 plot(sol)
 ```
+
+!!! note "Nota bene"
+
+    The `solve` function has options, see the [solve tutorial](@ref tutorial-solve). You can customise the plot with the `plot` function, see the [plot tutorial](@ref tutorial-plot).