Review the documentation

.gitignore

@@ -30,3 +30,6 @@ Manifest.toml
 **/Manifest.toml
 # ...except the one inside docs/src/assets
 !docs/src/assets/Manifest.toml
+
+# generated doc for the problems
+docs/src/problems

Project.toml

@@ -5,6 +5,10 @@ version = "0.2.1"
 
 [deps]
 CTBase = "54762871-cc72-4466-b8e8-f6c8b58076cd"
+CTModels = "34c4fa32-2049-4079-8329-de33c2a22e2d"
+DocStringExtensions = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
+ExaModels = "1037b233-b668-4ce9-9b63-f9f681f55dd2"
+OrderedCollections = "bac558e1-5e72-5ebc-8fee-abe8a469f55d"
 
 [weakdeps]
 JuMP = "4076af6c-e467-56ae-b986-b466b2749572"
@@ -16,6 +20,10 @@ OptimalControlModels = "OptimalControl"
 
 [compat]
 CTBase = "0.16"
+CTModels = "0.6.3"
+DocStringExtensions = "0.9.5"
+ExaModels = "0.9.0"
 JuMP = "1.28"
 OptimalControl = "1.1"
+OrderedCollections = "1.8.1"
 julia = "1.10"

docs/Project.toml

@@ -1,10 +1,16 @@
 [deps]
+CTModels = "34c4fa32-2049-4079-8329-de33c2a22e2d"
+DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterInterLinks = "d12716ef-a0f6-4df4-a9f1-a5a34e75c656"
+ExaModels = "1037b233-b668-4ce9-9b63-f9f681f55dd2"
 Ipopt = "b6b21f68-93f8-5de0-b562-5493be1d77c9"
 JuMP = "4076af6c-e467-56ae-b986-b466b2749572"
 Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"
+NLPModels = "a4795742-8479-5a88-8948-cc11e1c8c1a6"
 NLPModelsIpopt = "f4238b75-b362-5c4c-b852-0801c9a21d71"
 OptimalControl = "5f98b655-cc9a-415a-b60e-744165666948"
+Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
 TOML = "fa267f1f-6049-4f14-aa54-33bafae1ed76"
 
 [compat]

docs/make.jl

@@ -1,4 +1,55 @@
 using Documenter
+using DocumenterInterLinks
+using OptimalControlProblems
+using OptimalControl
+using JuMP
+using CTModels
+using ExaModels
+include("problems.jl")
+
+# to add docstrings from external packages
+const JuMPModels = Base.get_extension(OptimalControlProblems, :JuMPModels)
+const OptimalControlModels = Base.get_extension(OptimalControlProblems, :OptimalControlModels)
+
+Modules = [JuMPModels, OptimalControlModels]
+for Module in Modules
+    isnothing(DocMeta.getdocmeta(Module, :DocTestSetup)) &&
+        DocMeta.setdocmeta!(Module, :DocTestSetup, :(using $Module); recursive=true)
+end
+
+#
+links = InterLinks(
+    "ADNLPModels" => (
+        "https://jso.dev/ADNLPModels.jl/stable/",
+        "https://jso.dev/ADNLPModels.jl/stable/objects.inv",
+        joinpath(@__DIR__, "inventories", "ADNLPModels.toml"),
+    ),
+    "CTDirect" => (
+        "https://control-toolbox.org/CTDirect.jl/stable/",
+        "https://control-toolbox.org/CTDirect.jl/stable/objects.inv",
+        joinpath(@__DIR__, "inventories", "CTDirect.toml"),
+    ),
+    "JuMP" => (
+        "https://jump.dev/JuMP.jl/stable/",
+        "https://jump.dev/JuMP.jl/stable/objects.inv",
+        joinpath(@__DIR__, "inventories", "JuMP.toml"),
+    ),
+    "NLPModelsIpopt" => (
+        "https://jso.dev/NLPModelsIpopt.jl/stable/",
+        "https://jso.dev/NLPModelsIpopt.jl/stable/objects.inv",
+        joinpath(@__DIR__, "inventories", "NLPModelsIpopt.toml"),
+    ),
+    "OptimalControl" => (
+        "https://control-toolbox.org/OptimalControl.jl/stable/",
+        "https://control-toolbox.org/OptimalControl.jl/stable/objects.inv",
+        joinpath(@__DIR__, "inventories", "OptimalControl.toml"),
+    ),
+    "Tutorials" => (
+        "https://control-toolbox.org/Tutorials.jl/stable/",
+        "https://control-toolbox.org/Tutorials.jl/stable/objects.inv",
+        joinpath(@__DIR__, "inventories", "Tutorials.toml"),
+    ),
+)
 
 # For reproducibility
 mkpath(joinpath(@__DIR__, "src", "assets"))
@@ -15,28 +66,50 @@ cp(
 
 repo_url = "github.com/control-toolbox/OptimalControlProblems.jl"
 
+#
+draft = false
+exclude_from_draft=Symbol[
+#    :beam
+]
+PROBLEMS_PAGES = generate_documentation_problems(; draft=draft, exclude_from_draft=exclude_from_draft)
+
 makedocs(;
-    remotes=nothing,
+    draft=draft, # if draft is true, then the julia code from .md is not executed # debug
+    # to disable the draft mode in a specific markdown file, use the following:
+    # ```@meta
+    # Draft = false
+    # ```
+    #remotes=nothing,
     warnonly=:cross_references,
     sitename="OptimalControlProblems.jl",
     format=Documenter.HTML(;
         repolink="https://" * repo_url,
         prettyurls=false,
-        size_threshold_ignore=["index.md"],
+        size_threshold_ignore=[
+            "dev-api.md",
+            PROBLEMS_PAGES...
+        ],
         assets=[
             asset("https://control-toolbox.org/assets/css/documentation.css"),
             asset("https://control-toolbox.org/assets/js/documentation.js"),
         ],
     ),
     pages=[
         "Getting Started" => "index.md",
-        "List of the Problems" => "list_of_problems.md",
+        "Problems" => [
+            "problems-introduction.md",
+            "List of the problems" => PROBLEMS_PAGES
+        ],
         "Tutorials" => [
-            "How to get a problem" => "use_models.md",
-            "How to solve a problem" => "solve_problem.md",
+            "How to get a problem" => "tutorial-get.md",
+            "How to solve a problem" => "tutorial-solve.md",
+        ],
+        "Developers" => [
+            "How to add a problem" => "dev-add.md",
+            "API" => "dev-api.md"
         ],
-        "Developers" => ["How to add a problem" => "add_problem.md"],
     ],
+    plugins=[links],
 )
 
-deploydocs(; repo=repo_url * ".git", devbranch="main")
+deploydocs(; repo=repo_url * ".git", devbranch="main", push_preview=true)