Merge pull request #312 from control-toolbox/303-present-ct-repl-in-t…

…he-documentation

303 present ct repl in the documentation

docs/make.jl

@@ -34,12 +34,13 @@ makedocs(
             "Time mininimisation" => "tutorial-double-integrator.md",
         ],
         "Manual" => [
-            "Abstract syntax"   => "tutorial-abstract.md",
-            "Initial guess"     => "tutorial-initial-guess.md",
-            "Solve"             => "tutorial-solve.md",
-            "Plot a solution"   => "tutorial-plot.md",
-            "Flow"              => "tutorial-flow.md",
-            "Functional syntax" => "tutorial-functional.md",
+            "Abstract syntax"       => "tutorial-abstract.md",
+            "Initial guess"         => "tutorial-initial-guess.md",
+            "Solve"                 => "tutorial-solve.md",
+            "Plot a solution"       => "tutorial-plot.md",
+            "Flow"                  => "tutorial-flow.md",
+            "Functional syntax"     => "tutorial-functional.md",
+            "Control-toolbox REPL"  => "tutorial-repl.md",
         ],
         "Tutorials" => [
             "tutorial-continuation.md",

docs/src/tutorial-abstract.md

@@ -1,4 +1,4 @@
-# [The abstract syntax to define an optimal control problem](@id abstract)
+# [The abstract syntax to define an optimal control problem](@id tutorial-abstract)
 
 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-repl.md

@@ -0,0 +1,82 @@
+# The control-toolbox REPL
+
+We present in this tutorial the control-toolbox REPL which permits first an incremental 
+definition of the optimal control problem, but also to solve it (with default options only) 
+and plot the solution (with default options only). 
+
+- To define the problem please check the [abstract syntax tutorial](@ref tutorial-abstract).
+- For more details about solving an optimal control problem, we refer to the [solve tutorial](@ref tutorial-solve) and to plot a solution, check the [plot a solution tutorial](@ref tutorial-plot).
+
+To enter into the control-toolbox, press `>` key.
+
+!!! tip "Standard usage"
+
+    You can define the problem under the control-toolbox REPL and then, solve it
+    and plot the solution in the Julia REPL. Use the command `NAME` to rename the 
+    optimal control problem: `ct> NAME=ocp`.
+
+![Control-toolbox REPL](assets/ct-repl-95x30.gif)
+
+!!! note "Credits"
+
+    This gif has been made with this version of [Replay.jl](https://github.com/ocots/Replay.jl). To make the gif we first need a script (named ct-repl.jl) containing:
+
+    ```julia
+    using Replay
+
+    repl_script = """
+    using OptimalControl
+    t0 = 0
+    tf = 1
+    # press ">" to enter into control-toolbox repl
+    >t ∈ [t0, tf], time
+    # rename the ocp and the sol 
+    NAME=(ocp, sol)
+    SHOW
+    # more commands
+    HELP
+    # add ";" at the end of the line for no output
+    x ∈ R^2, state;
+    u ∈ R, control;
+    x(t0) == [ -1, 0 ];
+    x(tf) == [ 0, 0 ];
+    \\partial$(TAB)(x)(t) == [ x\\_2$(TAB)(t), u(t) ];
+    \\int$(TAB)( 0.5u(t)^2 ) \\to$(TAB) min;
+    SHOW
+    $BACKSPACE
+    using NLPModelsIpopt
+    >SOLVE
+    $BACKSPACE
+    # you can access the ocp and the sol in Julia repl
+    ocp
+    sol
+    using Plots
+    >PLOT
+    $BACKSPACE
+    """
+
+    replay(
+        repl_script, 
+        stdout, 
+        julia_project=@__DIR__, 
+        use_ghostwriter=true, 
+        cmd=`--color=yes`
+    )
+    ```
+
+    Then, to register the terminal we have used 
+    [asciinema](https://github.com/asciinema/asciinema) 
+    and to save the record into a gif file, we have used 
+    [agg](https://github.com/asciinema/agg). 
+    The shell script to obtain the gif is:
+
+    ```bash
+    julia --project=@. -e 'using Pkg; Pkg.instantiate()'
+    asciinema rec result.cast \
+        -i 2 \
+        --cols=95 \
+        --rows=30 \
+        --overwrite \
+        --command "julia --project=@. ./ct-repl.jl"
+    agg result.cast ct-repl.gif
+    ```

docs/src/tutorial-solve.md

@@ -1,4 +1,4 @@
-# [The solve function](@id manual-solve)
+# [The solve function](@id tutorial-solve)
 
 In this tutorial, we explain the [`solve`](@ref) function from [OptimalControl.jl](https://control-toolbox.org/OptimalControl.jl) package.