Merge pull request #455 from control-toolbox/move-ctsolvers-to-ctbase

Move CTSolvers core infrastructure to CTBase

Author: ocots

.github/workflows/SpellCheck.yml

@@ -7,3 +7,5 @@ on:
 jobs:
   call:
     uses: control-toolbox/CTActions/.github/workflows/spell-check.yml@main
+    with:
+      config-path: '_typos.toml'

Project.toml

@@ -1,6 +1,6 @@
 name = "CTBase"
 uuid = "54762871-cc72-4466-b8e8-f6c8b58076cd"
-version = "0.20.0-beta"
+version = "0.21.0-beta"
 authors = ["Olivier Cots <olivier.cots@irit.fr>", "Jean-Baptiste Caillau <caillau@univ-cotedazur.fr>"]
 
 [deps]

_typos.toml

@@ -0,0 +1,16 @@
+[default]
+locale = "en"
+extend-ignore-re = [
+    "adnlp_backen",
+    "ipopt_backen",
+    # Common variable names in our codebase
+    "strat",
+    "Strat",
+]
+
+[files]
+extend-exclude = [
+    "*.json",
+    "*.toml",
+    "*.svg",
+]

docs/README.md

@@ -13,3 +13,22 @@ Preview after build: `npx serve docs/build/1 --listen 5173`
 
 Documentation conventions and build workflow:
 [control-toolbox Handbook](https://github.com/control-toolbox/Handbook).
+
+## `@repl` vs `@example` — ANSI color rule
+
+DocumenterVitepress processes code block output differently depending on how it is produced:
+
+| Block type | Output fence | ANSI codes | Result |
+| --- | --- | --- | --- |
+| `@example` | ` ```ansi ` | processed by Shiki | **colors render correctly** |
+| `@repl` | ` ```julia ` | parsed as Julia syntax | **raw escape sequences — ugly** |
+
+**Rules:**
+
+- Use **`@example`** when the output comes from a `show` method that uses ANSI colors
+  (strategy instances, `StrategyOptions`, `StrategyMetadata`, `StrategyRegistry`, …).
+- Use **`@repl`** only when the output is a plain scalar value with no custom colored `show`
+  (integers, booleans, symbols, plain strings, tuples of symbols, types).
+- Use **`@repl` + `try/catch # hide` + `showerror(IOContext(stdout, :color => false), e) # hide`**
+  to display exceptions — the `showerror` call produces plain text that renders cleanly inside a
+  `julia`-fenced block.

docs/api_reference.jl

@@ -23,28 +23,56 @@ function generate_api_reference(src_dir::String)
             joinpath("Core", "types.jl"), joinpath("Core", "matrix_utils.jl"),
             joinpath("Core", "function_utils.jl"), joinpath("Core", "macros.jl"),
         )),
-        (mod=CTBase.Interpolation, title="Interpolation", filename="interpolation", files=src(
-            joinpath("Interpolation", "Interpolation.jl"), joinpath("Interpolation", "types.jl"),
-            joinpath("Interpolation", "ctinterpolate.jl"), joinpath("Interpolation", "display.jl"),
-        )),
         (mod=CTBase.Descriptions, title="Descriptions", filename="descriptions", files=src(
             joinpath("Descriptions", "Descriptions.jl"), joinpath("Descriptions", "types.jl"),
             joinpath("Descriptions", "similarity.jl"), joinpath("Descriptions", "display.jl"),
             joinpath("Descriptions", "catalog.jl"), joinpath("Descriptions", "complete.jl"),
             joinpath("Descriptions", "remove.jl"),
         )),
+        (mod=CTBase.DevTools, title="DevTools", filename="devtools", files=src(
+            joinpath("DevTools", "DevTools.jl"), joinpath("DevTools", "coverage_postprocessing.jl"),
+            joinpath("DevTools", "documenter_reference.jl"), joinpath("DevTools", "test_runner.jl"),
+        )),
         (mod=CTBase.Exceptions, title="Exceptions", filename="exceptions", files=src(
             joinpath("Exceptions", "Exceptions.jl"), joinpath("Exceptions", "types.jl"),
             joinpath("Exceptions", "display.jl"),
         )),
+        (mod=CTBase.Interpolation, title="Interpolation", filename="interpolation", files=src(
+            joinpath("Interpolation", "Interpolation.jl"), joinpath("Interpolation", "types.jl"),
+            joinpath("Interpolation", "ctinterpolate.jl"), joinpath("Interpolation", "display.jl"),
+        )),
+        (mod=CTBase.Options, title="Options", filename="options", files=src(
+            joinpath("Options", "Options.jl"), joinpath("Options", "not_provided.jl"),
+            joinpath("Options", "option_value.jl"), joinpath("Options", "option_definition.jl"),
+            joinpath("Options", "extraction.jl"),
+        )),
+        (mod=CTBase.Orchestration, title="Orchestration", filename="orchestration", files=src(
+            joinpath("Orchestration", "Orchestration.jl"),
+            joinpath("Orchestration", "disambiguation.jl"),
+            joinpath("Orchestration", "builders.jl"),
+            joinpath("Orchestration", "routing.jl"),
+        )),
+        (mod=CTBase.Strategies, title="Strategies", filename="strategies", files=src(
+            joinpath("Strategies", "Strategies.jl"),
+            joinpath("Strategies", "display_formatting.jl"),
+            joinpath("Strategies", "contract", "abstract_strategy.jl"),
+            joinpath("Strategies", "contract", "metadata.jl"),
+            joinpath("Strategies", "contract", "strategy_options.jl"),
+            joinpath("Strategies", "contract", "parameters.jl"),
+            joinpath("Strategies", "api", "registry.jl"),
+            joinpath("Strategies", "api", "describe_registry.jl"),
+            joinpath("Strategies", "api", "introspection.jl"),
+            joinpath("Strategies", "api", "bypass.jl"),
+            joinpath("Strategies", "api", "builders.jl"),
+            joinpath("Strategies", "api", "configuration.jl"),
+            joinpath("Strategies", "api", "utilities.jl"),
+            joinpath("Strategies", "api", "validation_helpers.jl"),
+            joinpath("Strategies", "api", "disambiguation.jl"),
+        )),
         (mod=CTBase.Unicode, title="Unicode", filename="unicode", files=src(
             joinpath("Unicode", "Unicode.jl"), joinpath("Unicode", "subscripts.jl"),
             joinpath("Unicode", "superscripts.jl"),
         )),
-        (mod=CTBase.DevTools, title="DevTools", filename="devtools", files=src(
-            joinpath("DevTools", "DevTools.jl"), joinpath("DevTools", "coverage_postprocessing.jl"),
-            joinpath("DevTools", "documenter_reference.jl"), joinpath("DevTools", "test_runner.jl"),
-        )),
     ]
 
     pages = [

docs/make.jl

@@ -69,9 +69,17 @@ with_api_reference(src_dir) do api_pages
         ),
         pages=[
             "Getting Started" => "getting-started.md",
-            "User Guides" => [
+            "Core Concepts" => [
                 "Descriptions" => joinpath("guide", "descriptions.md"),
                 "Exceptions" => joinpath("guide", "exceptions.md"),
+            ],
+            "Strategies & Options" => [
+                "Options System" => joinpath("guide", "options-system.md"),
+                "Implementing a Strategy" => joinpath("guide", "implementing-a-strategy.md"),
+                "Strategy Parameters" => joinpath("guide", "strategy-parameters.md"),
+                "Orchestration & Routing" => joinpath("guide", "orchestration-and-routing.md"),
+            ],
+            "Developer Tools" => [
                 "Test Runner" => joinpath("guide", "test-runner.md"),
                 "Coverage" => joinpath("guide", "coverage.md"),
                 "API Documentation" => joinpath("guide", "api-documentation.md"),