Merge pull request #313 from control-toolbox/doc

review intro doc

docs/src/index.md

@@ -4,19 +4,23 @@
 CurrentModule =  OptimalControl
 ```
 
-The [OptimalControl.jl](https://control-toolbox.org/OptimalControl.jl) package aims to provide tools to solve optimal control problems by direct and indirect methods.
-It is part of the [control-toolbox ecosystem](https://github.com/control-toolbox).
+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:
 
-!!! note "Install and documentation"
+```julia
+julia> ]
+pkg> add OptimalControl
+```
 
-    To install a package from the control-toolbox ecosystem, 
-    please visit the [installation page](https://github.com/control-toolbox#installation).
-    The documentation is accessible from the main menu.
+## Mathematical problem
 
-A (nonautonomous) optimal control problem with possibly free and final times can be described as minimising the cost functional
-s
+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
@@ -40,4 +44,60 @@ and other constraints such as
 \end{array}
 ```
 
-See our tutorials to get started solving optimal control problems.
+## Basic usage
+
+Let us modelise, solve and plot a simple optimal control problem.
+
+```julia
+using OptimalControl
+using NLPModelsIpopt
+using Plots
+
+ocp = @def begin
+    t ∈ [0, 1], time
+    x ∈ R², state
+    u ∈ R, control
+    x(0) == [ -1, 0 ]
+    x(1) == [ 0, 0 ]
+    ẋ(t) == [ x₂(t), u(t) ]
+    ∫( 0.5u(t)^2 ) → min
+end
+
+sol = solve(ocp)
+
+plot(sol)
+```
+
+For more details about this problem, please check the
+[basic example tutorial](@ref tutorial-basic). 
+For a comprehensive introduction to the syntax used above to describe the optimal control problem, check the
+[abstract syntax tutorial](@ref tutorial-abstract).
+
+## How to cite
+
+If you use OptimalControl.jl in your work, please cite us:
+
+> Caillau, J., Cots, O., Gergaud, J., Martinon, P., & Sed, S. *OptimalControl.jl: a Julia package to modelise and solve optimal control problems with ODE's* [Computer software]. https://doi.org/10.5281/zenodo.13336563
+
+or in bibtex format:
+
+```bibtex
+@software{Caillau_OptimalControl_jl_a_Julia,
+author = {Caillau, Jean-Baptiste and Cots, Olivier and Gergaud, Joseph and Martinon, Pierre and Sed, Sophia},
+doi = {10.5281/zenodo.13336563},
+license = {["MIT"]},
+title = {{OptimalControl.jl: a Julia package to modelise and solve optimal control problems with ODE's}},
+url = {https://control-toolbox.org/OptimalControl.jl}
+}
+```
+
+## Contributing
+
+If you think you found a bug or if you have a feature request or suggestion, feel free to open an [issue](https://github.com/control-toolbox/OptimalControl.jl/issues).
+Before opening a pull request, start an issue or a discussion on the topic, please. 
+
+Any 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, at the [first good issues page](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), so questions about any of our packages are welcome.

docs/src/tutorial-basic-example.md

@@ -1,4 +1,4 @@
-# [Double integrator: energy min (abstract syntax)](@id basic)
+# [Double integrator: energy min (abstract syntax)](@id tutorial-basic)
 
 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$.

docs/src/tutorial-flow.md

@@ -127,7 +127,7 @@ nothing # hide
 ```
 
 In this case, you obtain a data that you can plot exactly like when solving the optimal control problem 
-with the function `solve`. See for instance the [basic example](@ref basic-solve-plot) or the 
+with the function `solve`. See for instance the [basic example](@ref tutorial-basic-solve-plot) or the 
 [plot tutorial](@ref tutorial-plot).
 
 ```@example main

docs/src/tutorial-functional.md

@@ -2,7 +2,7 @@
 
 There are two syntaxes to define an optimal control problem with OptimalControl.jl:
 
-- the standard way is to use the abstract syntax. See for instance [basic example](@ref basic) for a start or for a comprehensive introduction to the abstract syntax, check [this tutorial](@ref abstract).
+- the standard way is to use the abstract syntax. See for instance [basic example](@ref tutorial-basic) for a start or for a comprehensive introduction to the abstract syntax, check [this tutorial](@ref abstract).
 - the old-fashioned functional syntax. In this tutorial with give two examples defined with the functional syntax. For more details please check the [`Model` documentation](@ref api-ctbase-model).
 
 ## Double integrator: energy minimisation
@@ -52,7 +52,7 @@ nothing # hide
 
 !!! note "Nota bene"
 
-    This problem is defined with the abstract syntax [here](@ref basic).
+    This problem is defined with the abstract syntax [here](@ref tutorial-basic).
 
 ## Double integrator: time minimisation