up doc

Author: ocots

.github/ISSUE_TEMPLATE/blank-issue.md

@@ -1,7 +1,7 @@
 ---
 name: Blank issue
 about: Blank template for general issue
-title: "[General] title"
+title: "[General] "
 labels: ''
 assignees: ocots
 

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,7 +1,7 @@
 ---
 name: Bug report
 about: Create a bug report to help us improve
-title: "[Bug] title"
+title: "[Bug] "
 labels: bug
 assignees: ocots
 

.github/ISSUE_TEMPLATE/developers.md

@@ -1,7 +1,7 @@
 ---
 name: 'Developers '
 about: Suggest internal modifications
-title: "[Dev] title"
+title: "[Dev] "
 labels: internal dev
 assignees: ocots
 

.github/ISSUE_TEMPLATE/documentation-suggestion.md

@@ -1,7 +1,7 @@
 ---
 name: Documentation suggestion
 about: Suggest improvements or additions to the documentation
-title: "[Doc] title"
+title: "[Doc] "
 labels: documentation
 assignees: ocots
 

.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,7 +1,7 @@
 ---
 name: Feature request
 about: Suggest an idea for this project
-title: "[Feature] title"
+title: "[Feature] "
 labels: enhancement
 assignees: ocots
 

Project.toml

@@ -1,7 +1,7 @@
 name = "CTBase"
 uuid = "54762871-cc72-4466-b8e8-f6c8b58076cd"
 authors = ["Olivier Cots <olivier.cots@irit.fr>", "Jean-Baptiste Caillau <caillau@univ-cotedazur.fr>"]
-version = "0.15.0"
+version = "0.15.1"
 
 [deps]
 DocStringExtensions = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"

docs/make.jl

@@ -2,6 +2,13 @@ using Documenter
 using CTBase
 using DocumenterMermaid
 
+# to add docstrings from external packages
+Modules = [Base]
+for Module in Modules
+    isnothing(DocMeta.getdocmeta(Module, :DocTestSetup)) &&
+        DocMeta.setdocmeta!(Module, :DocTestSetup, :(using $Module); recursive=true)
+end
+
 repo_url = "github.com/control-toolbox/CTBase.jl"
 
 makedocs(;
@@ -16,7 +23,7 @@ makedocs(;
             asset("https://control-toolbox.org/assets/js/documentation.js"),
         ],
     ),
-    pages=["Introduction" => "index.md", "API" => "api.md", "Developers" => "dev.md"],
+    pages=["Introduction" => "index.md", "Developers" => "dev.md"],
     checkdocs=:none,
 )
 

docs/src/api.md

@@ -1,21 +1,21 @@
 # Private functions
 
 ```@meta
-CollapsedDocStrings = true
+CollapsedDocStrings = false
 ```
 
 ## Index
 
 ```@index
 Pages   = ["dev.md"]
-Modules = [CTBase]
+Modules = [CTBase, Base]
 Order   = [:module, :constant, :type, :function, :macro]
 ```
 
 ## Documentation
 
 ```@autodocs
 Modules = [CTBase]
-Order   = [:module, :constant, :type, :function, :macro]
+Order   = [:type, :module, :constant, :type, :function, :macro]
 Public  = false
-```
+```

docs/src/dev.md

@@ -8,10 +8,22 @@ The `CTBase.jl` package is part of the [control-toolbox ecosystem](https://githu
 
 ```mermaid
 flowchart TD
-O(<a href='https://control-toolbox.org/OptimalControl.jl/stable/'>OptimalControl</a>) --> B(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctbase.html'>CTBase</a>)
-O --> D(<a href='https://control-toolbox.org/OptimalControl.jl/stable/api-ctdirect.html'>CTDirect</a>)
-O --> 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/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>)
+O --> D
+O --> M
+O --> F
+O --> P
+F --> M
+O --> B
 F --> B
 D --> B
+D --> M
+P --> B
+M --> B
 style B fill:#FBF275
-```
+```

docs/src/index.md

@@ -4,10 +4,6 @@
 Lists all the imported modules and packages:
 
 $(IMPORTS)
-
-List of all the exported names:
-
-$(EXPORTS)
 """
 module CTBase
 

src/CTBase.jl

@@ -2,6 +2,6 @@
 $(TYPEDSIGNATURES)
 
 Used to set the default value of the display argument.
-The default value is `true`, which means that the output is printed during resolution.
+The default value is `true`, which means that the output is printed during execution.
 """
 __display()::Bool = true

src/default.jl

@@ -67,13 +67,15 @@ julia> descriptions[1]
 (:a,)
 ```
 """
-add(x::Tuple{}, y::Description)::Tuple{Vararg{Description}} = (y,)
+add(::Tuple{}, y::Description)::Tuple{Vararg{Description}} = (y,)
 
 """
 $(TYPEDSIGNATURES)
 
-Concatenate the description `y` to the tuple of descriptions `x` if `x` does not contain `y`
-and return the new tuple of descriptions. Throw an error if the description `y` is already contained in `x`.
+Add the description `y` to the tuple of descriptions `x` if `x` does not contain `y`
+and return the new tuple of descriptions. 
+
+Throw an exception (IncorrectArgument) if the description `y` is already contained in `x`.
 
 # Example
 
@@ -99,35 +101,44 @@ end
 """
 $(TYPEDSIGNATURES)
 
-Return a complete description from an incomplete description `desc` and 
-a list of complete descriptions `desc_list`. If several complete descriptions are possible, 
-then the first one is returned.
+Return one description from a list of Symbols `list` and a set of descriptions `D`. 
+If multiple descriptions are possible, then the first one is selected.
+
+If the list is not contained in any of the descriptions, then an exception is thrown.
 
 # Example
 
 ```@example
-julia> desc_list = ((:a, :b), (:b, :c), (:a, :c))
+julia> D = ((:a, :b), (:a, :b, :c), (:b, :c), (:a, :c))
 (:a, :b)
 (:b, :c)
 (:a, :c)
-julia> getFullDescription((:a,), desc_list)
+julia> complete(:a; descriptions=D)
 (:a, :b)
+julia> complete(:a, :c; descriptions=D)
+(:a, :b, :c)
+julia> complete((:a, :c); descriptions=D)
+(:a, :b, :c)
+julia> complete(:f; descriptions=D)
+ERROR: AmbiguousDescription: the description (:f,) is ambiguous / incorrect
 ```
 """
-function getFullDescription(
-    desc::Description, desc_list::Tuple{Vararg{Description}}
-)::Description
-    n = size(desc_list, 1)
+function complete(list::Symbol...; descriptions::Tuple{Vararg{Description}})::Description
+    n = size(descriptions, 1)
     table = zeros(Int8, n, 2)
     for i in range(1, n)
-        table[i, 1] = size(desc ∩ desc_list[i], 1)
-        table[i, 2] = desc ⊆ desc_list[i] ? 1 : 0
+        table[i, 1] = size(list ∩ descriptions[i], 1)
+        table[i, 2] = list ⊆ descriptions[i] ? 1 : 0
     end
     if maximum(table[:, 2]) == 0
-        throw(AmbiguousDescription(desc))
+        throw(AmbiguousDescription(list))
     end
     # argmax : Return the index or key of the maximal element in a collection.
-    return desc_list[argmax(table[:, 1])]
+    return descriptions[argmax(table[:, 1])]
+end
+
+function complete(list::Tuple{DescVarArg}; descriptions::Tuple{Vararg{Description}})::Description
+    return complete(list..., descriptions=descriptions)
 end
 
 """

src/description.jl

@@ -15,6 +15,13 @@ Exception thrown when the description is ambiguous / incorrect.
 **Fields**
 
 $(TYPEDFIELDS)
+
+**Example**
+
+```@example
+julia> complete(:f; descriptions=((:a, :b), (:a, :b, :c))
+ERROR: AmbiguousDescription: the description (:f,) is ambiguous / incorrect
+```
 """
 struct AmbiguousDescription <: CTException
     var::Tuple{Vararg{Symbol}}

src/exception.jl

@@ -2,6 +2,8 @@
 $(TYPEDSIGNATURES)
 
 Return `i` ∈ [0, 9] as a subscript.
+
+If `i` is not in the range, an exception is thrown.
 """
 function ctindice(i::Int)::Char
     if i < 0 || i > 9
@@ -14,6 +16,8 @@ end
 $(TYPEDSIGNATURES)
 
 Return `i` > 0 as a subscript.
+
+If `i` is not in the range, an exception is thrown.
 """
 function ctindices(i::Int)::String
     if i < 0
@@ -30,6 +34,8 @@ end
 $(TYPEDSIGNATURES)
 
 Return `i` ∈ [0, 9] as an upperscript.
+
+If `i` is not in the range, an exception is thrown.
 """
 function ctupperscript(i::Int)::Char
     if i < 0 || i > 9
@@ -56,6 +62,8 @@ end
 $(TYPEDSIGNATURES)
 
 Return `i` > 0 as an upperscript.
+
+If `i` is not in the range, an exception is thrown.
 """
 function ctupperscripts(i::Int)::String
     if i < 0

src/utils.jl

@@ -16,16 +16,16 @@ function test_description()
     algorithmes = CTBase.add(algorithmes, (:descent, :gradient, :backtracking))
     algorithmes = CTBase.add(algorithmes, (:descent, :gradient, :fixedstep))
 
-    @test CTBase.getFullDescription((:descent,), algorithmes) == (:descent, :bfgs, :bissection)
-    @test CTBase.getFullDescription((:bfgs,), algorithmes) == (:descent, :bfgs, :bissection)
-    @test CTBase.getFullDescription((:bissection,), algorithmes) == (:descent, :bfgs, :bissection)
-    @test CTBase.getFullDescription((:backtracking,), algorithmes) == (:descent, :bfgs, :backtracking)
-    @test CTBase.getFullDescription((:fixedstep,), algorithmes) == (:descent, :bfgs, :fixedstep)
-    @test CTBase.getFullDescription((:fixedstep, :gradient), algorithmes) == (:descent, :gradient, :fixedstep)
+    @test CTBase.complete((:descent,);              descriptions=algorithmes) == (:descent, :bfgs, :bissection)
+    @test CTBase.complete((:bfgs,);                 descriptions=algorithmes) == (:descent, :bfgs, :bissection)
+    @test CTBase.complete((:bissection,);           descriptions=algorithmes) == (:descent, :bfgs, :bissection)
+    @test CTBase.complete((:backtracking,);         descriptions=algorithmes) == (:descent, :bfgs, :backtracking)
+    @test CTBase.complete((:fixedstep,);            descriptions=algorithmes) == (:descent, :bfgs, :fixedstep)
+    @test CTBase.complete((:fixedstep, :gradient);  descriptions=algorithmes) == (:descent, :gradient, :fixedstep)
 
     # incorrect description
-    @test_throws CTBase.AmbiguousDescription CTBase.getFullDescription((:ttt,), algorithmes)
-    @test_throws CTBase.AmbiguousDescription CTBase.getFullDescription((:descent, :ttt), algorithmes)
+    @test_throws CTBase.AmbiguousDescription CTBase.complete((:ttt,);           descriptions=algorithmes)
+    @test_throws CTBase.AmbiguousDescription CTBase.complete((:descent, :ttt);  descriptions=algorithmes)
 
     # diff
     x = (:a, :b, :c)
@@ -37,16 +37,16 @@ function test_description()
     algorithmes = ()
     algorithmes = CTBase.add(algorithmes, (:a, :b, :c))
     algorithmes = CTBase.add(algorithmes, (:a, :b, :c, :d))
-    @test CTBase.getFullDescription((:a, :b), algorithmes) == (:a, :b, :c)
-    @test CTBase.getFullDescription((:a, :b, :c, :d), algorithmes) == (:a, :b, :c, :d)
+    @test CTBase.complete((:a, :b);         descriptions=algorithmes) == (:a, :b, :c)
+    @test CTBase.complete((:a, :b, :c, :d); descriptions=algorithmes) == (:a, :b, :c, :d)
 
     # inclusion and different sizes - switch ordering 
     # priority to the first with max shared elements
     algorithmes = ()
     algorithmes = CTBase.add(algorithmes, (:a, :b, :c, :d))
     algorithmes = CTBase.add(algorithmes, (:a, :b, :c))
-    @test CTBase.getFullDescription((:a, :b), algorithmes) == (:a, :b, :c, :d)
-    @test CTBase.getFullDescription((:a, :b, :c, :d), algorithmes) == (:a, :b, :c, :d)
+    @test CTBase.complete((:a, :b);         descriptions=algorithmes) == (:a, :b, :c, :d)
+    @test CTBase.complete((:a, :b, :c, :d); descriptions=algorithmes) == (:a, :b, :c, :d)
 
     # CTBase.add a description already in the list
     algorithmes = ()