Merge pull request #142 from control-toolbox/doc

Doc

Author: ocots

docs/Project.toml

@@ -1,3 +1,9 @@
 [deps]
+CTBase = "54762871-cc72-4466-b8e8-f6c8b58076cd"
+CTDirect = "790bbbee-bee9-49ee-8912-a9de031322d5"
+CTFlows = "1c39547c-7794-42f7-af83-d98194f657c2"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+MINPACK = "4854310b-de5a-5eb6-a2a5-c1dee2bd17f9"
 OptimalControl = "5f98b655-cc9a-415a-b60e-744165666948"
+Suppressor = "fd094767-a336-5f1f-9728-57cf17d0bbfb"

docs/make.jl

@@ -1,14 +1,32 @@
 using Documenter
 using OptimalControl
+using CTBase
+using CTFlows
+using CTDirect
+
+# https://stackoverflow.com/questions/70137119/how-to-include-the-docstring-for-a-function-from-another-package-in-my-julia-doc
+DocMeta.setdocmeta!(CTBase, :DocTestSetup, :(using CTBase); recursive = true)
+DocMeta.setdocmeta!(CTFlows, :DocTestSetup, :(using CTFlows); recursive = true)
+DocMeta.setdocmeta!(CTDirect, :DocTestSetup, :(using CTDirect); recursive = true)
+DocMeta.setdocmeta!(OptimalControl, :DocTestSetup, :(using OptimalControl); recursive = true)
 
 makedocs(
     sitename = "OptimalControl.jl",
     format = Documenter.HTML(prettyurls = false),
     pages = [
-        "Introduction" => "index.md",
-        "Tutorials" => ["basic-example.md", "goddard.md"],
-        "API" => "api.md",
-        "Developpers" => "dev-api.md"
+        "Introduction"  => "index.md",
+        "Tutorials"     => ["tutorial-basic-example.md", 
+                            "tutorial-goddard.md",
+                            "tutorial-model.md",
+                            "tutorial-solvers.md",
+                            "tutorial-init.md",
+                            "tutorial-plot.md",
+                            "tutorial-iss.md",
+                            "tutorial-ctrepl.md"],
+        "API"           => ["api.md", 
+                            "api-ctbase.md", 
+                            "api-ctflows.md", 
+                            "api-ctdirect.md"], 
     ]
 )
 

docs/src/api-ctbase.md

@@ -0,0 +1,21 @@
+# CTBase API
+
+This is just a dump of CTBase API documentation.
+For more details about `CTBase.jl` package, see the [documentation](https://control-toolbox.org/CTDocs.jl/ctbase).
+
+## Index
+
+```@index
+Pages   = ["api-ctbase.md"]
+Modules = [CTBase]
+Order = [:module, :constant, :type, :function, :macro]
+Private = false
+```
+
+## Documentation
+
+```@autodocs
+Modules = [CTBase]
+Order = [:module, :constant, :type, :function, :macro]
+Private = false
+```

docs/src/api-ctdirect.md

@@ -0,0 +1,21 @@
+# CTDirect API
+
+This is just a dump of CTDirect API documentation.
+For more details about `CTDirect.jl` package, see the [documentation](https://control-toolbox.org/CTDocs.jl/ctdirect).
+
+## Index
+
+```@index
+Pages   = ["api-ctdirect.md"]
+Modules = [CTDirect]
+Order = [:module, :constant, :type, :function, :macro]
+Private = false
+```
+
+## Documentation
+
+```@autodocs
+Modules = [CTDirect]
+Order = [:module, :constant, :type, :function, :macro]
+Private = false
+```

docs/src/api-ctflows.md

@@ -0,0 +1,21 @@
+# CTFlows API
+
+This is just a dump of CTFlows API documentation.
+For more details about `CTFlows.jl` package, see the [documentation](https://control-toolbox.org/CTDocs.jl/ctflows).
+
+## Index
+
+```@index
+Pages   = ["api-ctflows.md"]
+Modules = [CTFlows]
+Order = [:module, :constant, :type, :function, :macro]
+Private = false
+```
+
+## Documentation
+
+```@autodocs
+Modules = [CTFlows]
+Order = [:module, :constant, :type, :function, :macro]
+Private = false
+```

docs/src/api.md

@@ -1,10 +1,25 @@
-# API
+# OptimalControl API
 
-```@meta
-CurrentModule = OptimalControl
+## Index
+
+```@index
+Pages   = ["api.md"]
+Modules = [OptimalControl]
+Order = [:module, :constant, :type, :function, :macro]
+Private = false
+```
+
+## Available methods
+
+```@example
+using OptimalControl
+Methods()
 ```
 
+## Documentation
+
 ```@autodocs
 Modules = [OptimalControl]
-Order = [:module, :type, :function, :macro]
+Order = [:module, :constant, :type, :function, :macro]
+Private = false
 ```

docs/src/assets/Goddard_and_Rocket.jpg

@@ -4,17 +4,23 @@
 CurrentModule =  OptimalControl
 ```
 
-The `OptimalControl.jl` package is part of the [control-toolbox ecosystem](https://github.com/control-toolbox).
+The `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):
 
-!!! note "Install"
+```@raw html
+<img src="./assets/diagram.png" style="display: block; margin: 0 auto 20px auto;" width="320px">
+```
+
+!!! note "Install and documentation"
 
     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.
 
-This package aims to provide tools to solve optimal control problems by direct and indirect methods. An optimal control problem can be described as minimising the cost functional
+An optimal control problem with fixed 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
+g(x(t_0), 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]$,
@@ -34,3 +40,9 @@ and other constraints such as
 \phi_l &\le& \phi(t_0, x(t_0), t_f, x(t_f)) &\le& \phi_u.
 \end{array}
 ```
+
+See our tutorials to get started solving optimal control problems:
+
+- [Basic example](@ref): a simple smooth optimal control problem solved by the direct method.
+- [Advanced example](@ref): the [Goddard problem](https://en.wikipedia.org/w/index.php?title=Goddard_problem&oldid=1091155283) solved by direct and indirect methods.
+