From f262e0b35dc1ad536c350d48b6ad11d9ae323dca Mon Sep 17 00:00:00 2001
From: Olivier Cots <olivier.cots@irit.fr>
Date: Thu, 5 Mar 2026 10:26:00 +0100
Subject: [PATCH 1/3] refactor: clean up codebase and documentation

- Remove unused is_solvable function from collocation_core.jl
- Clean up documentation dependencies in docs/Project.toml
- Add documentation generation script docs/doc.jl
- Update imports and dependencies across multiple files
- Remove unused test files and dependencies
- General code cleanup and formatting improvements
---
 Project.toml            | 19 ++++++++--------
 docs/Project.toml       | 10 ---------
 docs/doc.jl             | 49 +++++++++++++++++++++++++++++++++++++++++
 src/CTDirect.jl         | 16 +++++++-------
 src/collocation.jl      |  8 +++----
 src/collocation_core.jl | 28 -----------------------
 src/disc/euler.jl       |  4 ++--
 src/disc/irk.jl         |  4 ++--
 src/disc/midpoint.jl    |  4 ++--
 src/disc/trapeze.jl     |  4 ++--
 test/test_common.jl     |  2 +-
 test/tmp/Project.toml   |  2 +-
 test/tmp/ocp.jl         |  1 -
 test/tmp/test_madnlp.jl |  2 +-
 14 files changed, 80 insertions(+), 73 deletions(-)
 create mode 100644 docs/doc.jl

diff --git a/Project.toml b/Project.toml
index 2eaeb058..571c9c48 100644
--- a/Project.toml
+++ b/Project.toml
@@ -1,6 +1,6 @@
 name = "CTDirect"
 uuid = "790bbbee-bee9-49ee-8912-a9de031322d5"
-version = "1.0.2-beta"
+version = "1.0.3-beta"
 authors = ["Pierre Martinon <pierrecmartinon@gmail.com>"]
 
 [workspace]
@@ -8,13 +8,10 @@ projects = ["test", "docs"]
 
 [deps]
 ADNLPModels = "54578032-b7ea-4c30-94aa-7cbd1cce6c9a"
-CTBase = "54762871-cc72-4466-b8e8-f6c8b58076cd"
 CTModels = "34c4fa32-2049-4079-8329-de33c2a22e2d"
-CTParser = "32681960-a1b1-40db-9bff-a1ca817385d1"
 CTSolvers = "d3e8d392-8e4b-4d9b-8e92-d7d4e3650ef6"
 DocStringExtensions = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
 ExaModels = "1037b233-b668-4ce9-9b63-f9f681f55dd2"
-NLPModels = "a4795742-8479-5a88-8948-cc11e1c8c1a6"
 SolverCore = "ff4d7338-4cf1-434d-91df-b86cb86fb843"
 SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
 
@@ -24,16 +21,16 @@ AMDGPU = "2"
 CTBase = "0.18"
 CTModels = "0.9"
 CTParser = "0.8"
-CTSolvers = "0.3"
+CTSolvers = "0.4"
 CUDA = "5"
 CommonSolve = "0.2"
 DocStringExtensions = "0.9"
 ExaModels = "0.9"
-MadNLPGPU = "0.7"
-MadNLPMumps = "0.5"
+MadNLP = "0.9"
+MadNLPGPU = "0.8"
 NLPModels = "0.21"
 NLPModelsIpopt = "0.11"
-SolverCore = "0.3.8"
+SolverCore = "0.3"
 SparseArrays = "1"
 SplitApplyCombine = "1"
 Test = "1"
@@ -41,14 +38,16 @@ julia = "1.10"
 
 [extras]
 AMDGPU = "21141c5a-9bdb-4563-92ae-f87d6854732e"
+CTBase = "54762871-cc72-4466-b8e8-f6c8b58076cd"
+CTParser = "32681960-a1b1-40db-9bff-a1ca817385d1"
 CUDA = "052768ef-5323-5732-b1bb-66c8b64840ba"
 CommonSolve = "38540f10-b2f7-11e9-35d8-d573e4eb0ff2"
+MadNLP = "2621e9c9-9eb4-46b1-8089-e8c72242dfb6"
 MadNLPGPU = "d72a61cc-809d-412f-99be-fd81f4b8a598"
-MadNLPMumps = "3b83494e-c0a4-4895-918b-9157a7a085a1"
 NLPModels = "a4795742-8479-5a88-8948-cc11e1c8c1a6"
 NLPModelsIpopt = "f4238b75-b362-5c4c-b852-0801c9a21d71"
 SplitApplyCombine = "03a91e81-4c3e-53e1-a0a4-9c0c8f19dd66"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [targets]
-test = ["AMDGPU", "CUDA", "CommonSolve", "MadNLPGPU", "MadNLPMumps", "NLPModels", "NLPModelsIpopt", "SplitApplyCombine", "Test"]
+test = ["AMDGPU", "CTBase", "CTParser", "CUDA", "CommonSolve", "MadNLP", "MadNLPGPU", "NLPModels", "NLPModelsIpopt", "SplitApplyCombine", "Test"]
diff --git a/docs/Project.toml b/docs/Project.toml
index 38e83952..16d3b4bf 100644
--- a/docs/Project.toml
+++ b/docs/Project.toml
@@ -1,17 +1,7 @@
 [deps]
-ADNLPModels = "54578032-b7ea-4c30-94aa-7cbd1cce6c9a"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterMermaid = "a078cd44-4d9c-4618-b545-3ab9d77f9177"
-ExaModels = "1037b233-b668-4ce9-9b63-f9f681f55dd2"
-MadNLP = "2621e9c9-9eb4-46b1-8089-e8c72242dfb6"
-MadNLPMumps = "3b83494e-c0a4-4895-918b-9157a7a085a1"
-NLPModelsIpopt = "f4238b75-b362-5c4c-b852-0801c9a21d71"
 
 [compat]
-ADNLPModels = "0.8"
 Documenter = "1"
 DocumenterMermaid = "0.2"
-ExaModels = "0.9"
-MadNLP = "0.8"
-NLPModelsIpopt = "0.11"
-MadNLPMumps = "0.5"
diff --git a/docs/doc.jl b/docs/doc.jl
new file mode 100644
index 00000000..58dd26c0
--- /dev/null
+++ b/docs/doc.jl
@@ -0,0 +1,49 @@
+#!/usr/bin/env julia
+
+"""
+    Documentation Generation Script for CTDirect.jl
+
+This script generates the documentation for CTDirect.jl and then removes
+CTDirect from the docs/Project.toml to keep it clean.
+
+Usage (from any directory):
+    julia docs/doc.jl
+    # OR
+    julia --project=. docs/doc.jl
+    # OR  
+    julia --project=docs docs/doc.jl
+
+The script will:
+1. Activate the docs environment
+2. Add CTDirect as a development dependency in docs environment
+3. Generate the documentation using docs/make.jl
+4. Remove CTDirect from docs/Project.toml
+5. Clean up the docs environment
+"""
+
+using Pkg
+
+println("🚀 Starting documentation generation for CTDirect.jl...")
+
+# Step 0: Activate docs environment (works from any directory)
+docs_dir = joinpath(@__DIR__)
+println("📁 Activating docs environment at: $docs_dir")
+Pkg.activate(docs_dir)
+
+# Step 1: Add CTDirect as development dependency
+println("📦 Adding CTDirect as development dependency...")
+# Get the project root (parent of docs directory)
+project_root = dirname(docs_dir)
+Pkg.develop(path=project_root)
+
+# Step 2: Generate documentation
+println("📚 Building documentation...")
+include(joinpath(docs_dir, "make.jl"))
+
+# Step 3: Remove CTDirect from docs environment
+println("🧹 Cleaning up docs environment...")
+Pkg.rm("CTDirect")
+
+println("✅ Documentation generated successfully!")
+println("📖 Documentation available at: $(joinpath(docs_dir, "build", "index.html"))")
+println("🗂️  CTDirect removed from docs/Project.toml")
\ No newline at end of file
diff --git a/src/CTDirect.jl b/src/CTDirect.jl
index 027303f6..f48da33a 100644
--- a/src/CTDirect.jl
+++ b/src/CTDirect.jl
@@ -1,14 +1,14 @@
 module CTDirect
 
-using ADNLPModels
-using ExaModels
-using CTBase
-using CTModels
-import CTSolvers, CTSolvers.Strategies, CTSolvers.Options
 using DocStringExtensions
-using SparseArrays
-using SolverCore
-using NLPModels
+import ADNLPModels
+import ExaModels
+import CTModels
+import CTSolvers, CTSolvers.Strategies, CTSolvers.Options
+import SolverCore
+import SparseArrays
+# using CTBase
+# using NLPModels
 
 # ----------------------------------------------------------------------
 # TYPES
diff --git a/src/collocation.jl b/src/collocation.jl
index 35d3e547..7f891804 100644
--- a/src/collocation.jl
+++ b/src/collocation.jl
@@ -174,7 +174,7 @@ function (discretizer::Collocation)(ocp::AbstractModel)
         end
 
         # build NLP
-        nlp = ADNLPModel!(
+        nlp = ADNLPModels.ADNLPModel!(
             f,
             init,
             docp.bounds.var_l,
@@ -195,8 +195,7 @@ function (discretizer::Collocation)(ocp::AbstractModel)
     function build_adnlp_solution(nlp_solution::SolverCore.AbstractExecutionStats)
         
         # retrieve data from NLP solver
-        minimize = !docp.flags.max
-        objective, iterations, constraints_violation, message, status, successful = CTSolvers.extract_solver_infos(nlp_solution, minimize)
+        objective, iterations, constraints_violation, message, status, successful = CTSolvers.extract_solver_infos(nlp_solution)
 
         # retrieve time grid
         T = get_time_grid(nlp_solution.solution, docp)
@@ -245,8 +244,7 @@ function (discretizer::Collocation)(ocp::AbstractModel)
         end
 
         # retrieve data from NLP solver
-        minimize = !docp.flags.max
-        objective, iterations, constraints_violation, message, status, successful = CTSolvers.extract_solver_infos(nlp_solution, minimize)
+        objective, iterations, constraints_violation, message, status, successful = CTSolvers.extract_solver_infos(nlp_solution)
   
         # retrieve time grid
         T = get_time_grid_exa(nlp_solution, docp, exa_getter)
diff --git a/src/collocation_core.jl b/src/collocation_core.jl
index 221f4a64..f6058cbc 100644
--- a/src/collocation_core.jl
+++ b/src/collocation_core.jl
@@ -404,33 +404,6 @@ DiscretizationModel(...)
 """
 disc_model(docp::DOCP) = docp.discretization
 
-
-"""
-$(TYPEDSIGNATURES)
-
-Check if an OCP is solvable by [`solve`](@ref).
-
-# Arguments
-
-- `ocp`: The OCP model.
-
-# Returns
-
-- `solvable::Bool`: Always returns `true` in the current implementation.
-
-# Example
-
-```julia-repl
-julia> is_solvable(ocp)
-true
-```
-"""
-function is_solvable(ocp)
-    solvable = true
-    return solvable
-end
-
-
 """
 $(TYPEDSIGNATURES)
 
@@ -507,7 +480,6 @@ true
 """
 is_empty(t) = (isnothing(t) || length(t) == 0)
 
-
 """
 $(TYPEDSIGNATURES)
 
diff --git a/src/disc/euler.jl b/src/disc/euler.jl
index b8d1787c..6e0d522b 100644
--- a/src/disc/euler.jl
+++ b/src/disc/euler.jl
@@ -287,7 +287,7 @@ function DOCP_Jacobian_pattern(docp::DOCP{Euler})
     # build and return sparse matrix
     nnzj = length(Is)
     Vs = ones(Bool, nnzj)
-    return sparse(Is, Js, Vs, docp.dim_NLP_constraints, docp.dim_NLP_variables)
+    return SparseArrays.sparse(Is, Js, Vs, docp.dim_NLP_constraints, docp.dim_NLP_variables)
 end
 
 """
@@ -377,5 +377,5 @@ function DOCP_Hessian_pattern(docp::DOCP{Euler})
     # build and return sparse matrix
     nnzj = length(Is)
     Vs = ones(Bool, nnzj)
-    return sparse(Is, Js, Vs, docp.dim_NLP_variables, docp.dim_NLP_variables)
+    return SparseArrays.sparse(Is, Js, Vs, docp.dim_NLP_variables, docp.dim_NLP_variables)
 end
diff --git a/src/disc/irk.jl b/src/disc/irk.jl
index 1aedbee3..00bd5837 100644
--- a/src/disc/irk.jl
+++ b/src/disc/irk.jl
@@ -457,7 +457,7 @@ function DOCP_Jacobian_pattern(docp::DOCP{<: GenericIRK})
     # build and return sparse matrix
     nnzj = length(Is)
     Vs = ones(Bool, nnzj)
-    return sparse(Is, Js, Vs, docp.dim_NLP_constraints, docp.dim_NLP_variables)
+    return SparseArrays.sparse(Is, Js, Vs, docp.dim_NLP_constraints, docp.dim_NLP_variables)
 end
 
 """
@@ -545,5 +545,5 @@ function DOCP_Hessian_pattern(docp::DOCP{<: GenericIRK})
     # build and return sparse matrix
     nnzj = length(Is)
     Vs = ones(Bool, nnzj)
-    return sparse(Is, Js, Vs, docp.dim_NLP_variables, docp.dim_NLP_variables)
+    return SparseArrays.sparse(Is, Js, Vs, docp.dim_NLP_variables, docp.dim_NLP_variables)
 end
diff --git a/src/disc/midpoint.jl b/src/disc/midpoint.jl
index 3f0bac1a..ad820215 100644
--- a/src/disc/midpoint.jl
+++ b/src/disc/midpoint.jl
@@ -212,7 +212,7 @@ function DOCP_Jacobian_pattern(docp::DOCP{Midpoint})
     # build and return sparse matrix
     nnzj = length(Is)
     Vs = ones(Bool, nnzj)
-    return sparse(Is, Js, Vs, docp.dim_NLP_constraints, docp.dim_NLP_variables)
+    return SparseArrays.sparse(Is, Js, Vs, docp.dim_NLP_constraints, docp.dim_NLP_variables)
 end
 
 """
@@ -279,5 +279,5 @@ function DOCP_Hessian_pattern(docp::DOCP{Midpoint})
     # build and return sparse matrix
     nnzj = length(Is)
     Vs = ones(Bool, nnzj)
-    return sparse(Is, Js, Vs, docp.dim_NLP_variables, docp.dim_NLP_variables)
+    return SparseArrays.sparse(Is, Js, Vs, docp.dim_NLP_variables, docp.dim_NLP_variables)
 end
diff --git a/src/disc/trapeze.jl b/src/disc/trapeze.jl
index d2fe3438..99a47702 100644
--- a/src/disc/trapeze.jl
+++ b/src/disc/trapeze.jl
@@ -251,7 +251,7 @@ function DOCP_Jacobian_pattern(docp::DOCP{Trapeze})
     # build and return sparse matrix
     nnzj = length(Is)
     Vs = ones(Bool, nnzj)
-    return sparse(Is, Js, Vs, docp.dim_NLP_constraints, docp.dim_NLP_variables)
+    return SparseArrays.sparse(Is, Js, Vs, docp.dim_NLP_constraints, docp.dim_NLP_variables)
 end
 
 """
@@ -321,5 +321,5 @@ function DOCP_Hessian_pattern(docp::DOCP{Trapeze})
     # build and return sparse matrix
     nnzj = length(Is)
     Vs = ones(Bool, nnzj)
-    return sparse(Is, Js, Vs, docp.dim_NLP_variables, docp.dim_NLP_variables)
+    return SparseArrays.sparse(Is, Js, Vs, docp.dim_NLP_variables, docp.dim_NLP_variables)
 end
diff --git a/test/test_common.jl b/test/test_common.jl
index 9781d318..65733ed8 100644
--- a/test/test_common.jl
+++ b/test/test_common.jl
@@ -15,7 +15,7 @@ using ExaModels
 # NLP solvers
 using NLPModels
 using NLPModelsIpopt
-using MadNLPMumps
+using MadNLP
 
 # misc
 using SplitApplyCombine # for flatten in some tests
diff --git a/test/tmp/Project.toml b/test/tmp/Project.toml
index 59325a13..a4ccc469 100644
--- a/test/tmp/Project.toml
+++ b/test/tmp/Project.toml
@@ -3,6 +3,6 @@ ADNLPModels = "54578032-b7ea-4c30-94aa-7cbd1cce6c9a"
 DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 ExaModels = "1037b233-b668-4ce9-9b63-f9f681f55dd2"
 Ipopt = "b6b21f68-93f8-5de0-b562-5493be1d77c9"
-MadNLPMumps = "3b83494e-c0a4-4895-918b-9157a7a085a1"
+MadNLP = "2621e9c9-9eb4-46b1-8089-e8c72242dfb6"
 NLPModels = "a4795742-8479-5a88-8948-cc11e1c8c1a6"
 NLPModelsIpopt = "f4238b75-b362-5c4c-b852-0801c9a21d71"
diff --git a/test/tmp/ocp.jl b/test/tmp/ocp.jl
index ed70fc6c..c5dcc316 100644
--- a/test/tmp/ocp.jl
+++ b/test/tmp/ocp.jl
@@ -30,5 +30,4 @@ sol = solve(ocp, :adnlp, :ipopt);
 # 
 using ExaModels
 using MadNLP
-#using MadNLPMumps
 sol = solve(ocp, :exa, :madnlp);
diff --git a/test/tmp/test_madnlp.jl b/test/tmp/test_madnlp.jl
index d68a0275..fa79699a 100644
--- a/test/tmp/test_madnlp.jl
+++ b/test/tmp/test_madnlp.jl
@@ -3,7 +3,7 @@ Pkg.activate(joinpath(@__DIR__))
 
 using NLPModels
 using ExaModels
-using MadNLPMumps
+using MadNLP
 using ADNLPModels
 using Ipopt
 using NLPModelsIpopt

From f923099947c0fc3cb4b614b84e6009e5eb9775e3 Mon Sep 17 00:00:00 2001
From: Olivier Cots <olivier.cots@irit.fr>
Date: Thu, 5 Mar 2026 22:11:18 +0100
Subject: [PATCH 2/3] feat: restructure documentation to use CTBase tools

- Replace manual API pages with automatic generation using CTBase.automatic_reference_documentation
- Create api_reference.jl inspired by CTSolvers.jl structure
- Update make.jl to use CTBase DocumenterReference extension
- Remove exports from CTDirect.jl to keep API private
- Generate coherent documentation organized by modules (Core, Collocation, Discretization)
- Add proper index.md with package overview
- Clean up old manual documentation files
---
 docs/Project.toml                 |   7 ++
 docs/api_reference.jl             | 116 ++++++++++++++++++++++++++
 docs/make.jl                      |  71 ++++++++++------
 docs/src/api/collocation.md       | 132 ++++++++++++++++++++++++++++++
 docs/src/api/core.md              |  20 +++++
 docs/src/api/discretization.md    | 132 ++++++++++++++++++++++++++++++
 docs/src/collocation.md           |  17 ----
 docs/src/collocation_core.md      |  17 ----
 docs/src/collocation_functions.md |  17 ----
 docs/src/collocation_variables.md |  17 ----
 docs/src/common.md                |  17 ----
 docs/src/docp.md                  |  17 ----
 docs/src/euler.md                 |  17 ----
 docs/src/index.md                 |   8 +-
 docs/src/irk.md                   |  17 ----
 docs/src/midpoint.md              |  17 ----
 docs/src/trapeze.md               |  17 ----
 src/CTDirect.jl                   |   1 +
 18 files changed, 456 insertions(+), 201 deletions(-)
 create mode 100644 docs/api_reference.jl
 create mode 100644 docs/src/api/collocation.md
 create mode 100644 docs/src/api/core.md
 create mode 100644 docs/src/api/discretization.md
 delete mode 100644 docs/src/collocation.md
 delete mode 100644 docs/src/collocation_core.md
 delete mode 100644 docs/src/collocation_functions.md
 delete mode 100644 docs/src/collocation_variables.md
 delete mode 100644 docs/src/common.md
 delete mode 100644 docs/src/docp.md
 delete mode 100644 docs/src/euler.md
 delete mode 100644 docs/src/irk.md
 delete mode 100644 docs/src/midpoint.md
 delete mode 100644 docs/src/trapeze.md

diff --git a/docs/Project.toml b/docs/Project.toml
index 16d3b4bf..ad7b2925 100644
--- a/docs/Project.toml
+++ b/docs/Project.toml
@@ -1,7 +1,14 @@
 [deps]
+CTBase = "54762871-cc72-4466-b8e8-f6c8b58076cd"
+CTDirect = "790bbbee-bee9-49ee-8912-a9de031322d5"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterMermaid = "a078cd44-4d9c-4618-b545-3ab9d77f9177"
+Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"
+MarkdownAST = "d0879d2d-cac2-40c8-9cee-1863dc0c7391"
 
 [compat]
+CTBase = "0.18"
 Documenter = "1"
 DocumenterMermaid = "0.2"
+Markdown = "1"
+MarkdownAST = "0.1"
diff --git a/docs/api_reference.jl b/docs/api_reference.jl
new file mode 100644
index 00000000..38af4358
--- /dev/null
+++ b/docs/api_reference.jl
@@ -0,0 +1,116 @@
+"""
+    generate_api_reference(src_dir::String, ext_dir::String)
+
+Generate the API reference documentation for CTDirect.
+Returns the list of pages.
+"""
+function generate_api_reference(src_dir::String, ext_dir::String)
+    # Helper to build absolute paths
+    src(files...) = [abspath(joinpath(src_dir, f)) for f in files]
+    ext(files...) = [abspath(joinpath(ext_dir, f)) for f in files]
+
+    # Symbols to exclude from documentation
+    EXCLUDE_SYMBOLS = Symbol[
+        :include,
+        :eval,
+    ]
+
+    pages = [
+
+        # ───────────────────────────────────────────────────────────────────
+        # Core Module
+        # ───────────────────────────────────────────────────────────────────
+        CTBase.automatic_reference_documentation(;
+            subdirectory="api",
+            primary_modules=[
+                CTDirect => src(
+                    "CTDirect.jl",
+                ),
+            ],
+            exclude=EXCLUDE_SYMBOLS,
+            public=false,
+            private=true,
+            title="Core Module",
+            title_in_menu="Core",
+            filename="core",
+        ),
+
+        # ───────────────────────────────────────────────────────────────────
+        # Collocation
+        # ───────────────────────────────────────────────────────────────────
+        CTBase.automatic_reference_documentation(;
+            subdirectory="api",
+            primary_modules=[
+                CTDirect => src(
+                    "collocation.jl",
+                    "collocation_core.jl",
+                    "collocation_variables.jl",
+                    "collocation_functions.jl",
+                ),
+            ],
+            exclude=EXCLUDE_SYMBOLS,
+            public=false,
+            private=true,
+            title="Collocation Methods",
+            title_in_menu="Collocation",
+            filename="collocation",
+        ),
+
+        # ───────────────────────────────────────────────────────────────────
+        # Discretization Schemes
+        # ───────────────────────────────────────────────────────────────────
+        CTBase.automatic_reference_documentation(;
+            subdirectory="api",
+            primary_modules=[
+                CTDirect => src(
+                    joinpath("disc", "common.jl"),
+                    joinpath("disc", "euler.jl"),
+                    joinpath("disc", "irk.jl"),
+                    joinpath("disc", "midpoint.jl"),
+                    joinpath("disc", "trapeze.jl"),
+                ),
+            ],
+            exclude=EXCLUDE_SYMBOLS,
+            public=false,
+            private=true,
+            title="Discretization Schemes",
+            title_in_menu="Discretization",
+            filename="discretization",
+        ),
+
+    ]
+
+    return pages
+end
+
+"""
+    with_api_reference(f::Function, src_dir::String, ext_dir::String)
+
+Generates the API reference, executes `f(pages)`, and cleans up generated files.
+"""
+function with_api_reference(f::Function, src_dir::String, ext_dir::String)
+    pages = generate_api_reference(src_dir, ext_dir)
+    try
+        f(pages)
+    finally
+        # Clean up generated files
+        docs_src = abspath(joinpath(@__DIR__, "src"))
+        _cleanup_pages(docs_src, pages)
+    end
+end
+
+function _cleanup_pages(docs_src::String, pages)
+    for p in pages
+        val = last(p)
+        if val isa AbstractString
+            fname = endswith(val, ".md") ? val : val * ".md"
+            full_path = joinpath(docs_src, fname)
+            if isfile(full_path)
+                rm(full_path)
+                println("Removed temporary API doc: $full_path")
+            end
+        elseif val isa AbstractVector
+            _cleanup_pages(docs_src, val)
+        end
+    end
+end
diff --git a/docs/make.jl b/docs/make.jl
index 77e31b7e..4208a1b4 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -1,34 +1,57 @@
 using Documenter
 using DocumenterMermaid
 using CTDirect
+using CTBase
+using Markdown
+using MarkdownAST: MarkdownAST
 
+# ═══════════════════════════════════════════════════════════════════════════════
+# Configuration
+# ═══════════════════════════════════════════════════════════════════════════════
+draft = false  # Draft mode: if true, @example blocks in markdown are not executed
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Load extensions
+# ═══════════════════════════════════════════════════════════════════════════════
+const DocumenterReference = Base.get_extension(CTBase, :DocumenterReference)
+
+if !isnothing(DocumenterReference)
+    DocumenterReference.reset_config!()
+end
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Paths
+# ═══════════════════════════════════════════════════════════════════════════════
 repo_url = "github.com/control-toolbox/CTDirect.jl"
+src_dir = abspath(joinpath(@__DIR__, "..", "src"))
+ext_dir = abspath(joinpath(@__DIR__, "..", "ext"))
 
-API_PAGES = [    
-    "collocation.md",
-    "collocation_functions.md",
-    "collocation_variables.md",
-    "collocation_core.md",    
-    "common.md",
-    "docp.md",
-    "euler.md",
-    "irk.md",
-    "midpoint.md",
-    "trapeze.md",
-]
+# Include the API reference manager
+include("api_reference.jl")
 
-makedocs(;
-    warnonly=[:cross_references, :autodocs_block],
-    sitename="CTDirect.jl",
-    format=Documenter.HTML(;
-        repolink="https://" * repo_url,
-        prettyurls=false,
-        assets=[
-            asset("https://control-toolbox.org/assets/css/documentation.css"),
-            asset("https://control-toolbox.org/assets/js/documentation.js"),
+# ═══════════════════════════════════════════════════════════════════════════════
+# Build documentation
+# ═══════════════════════════════════════════════════════════════════════════════
+with_api_reference(src_dir, ext_dir) do api_pages
+    makedocs(;
+        draft=draft,
+        remotes=nothing, # Disable remote links. Needed for DocumenterReference
+        warnonly=true,
+        sitename="CTDirect.jl",
+        format=Documenter.HTML(;
+            repolink="https://" * repo_url,
+            prettyurls=false,
+            assets=[
+                asset("https://control-toolbox.org/assets/css/documentation.css"),
+                asset("https://control-toolbox.org/assets/js/documentation.js"),
+            ],
+        ),
+        pages=[
+            "Introduction" => "index.md",
+            "API Reference" => api_pages,
         ],
-    ),
-    pages=["Introduction" => "index.md", "API" => API_PAGES],
-)
+    )
+end
 
+# ═══════════════════════════════════════════════════════════════════════════════
 deploydocs(; repo=repo_url * ".git", devbranch="main")
diff --git a/docs/src/api/collocation.md b/docs/src/api/collocation.md
new file mode 100644
index 00000000..f693000e
--- /dev/null
+++ b/docs/src/api/collocation.md
@@ -0,0 +1,132 @@
+```@meta
+EditURL = nothing
+```
+
+# Private API
+
+This page lists **non-exported** (internal) symbols of `CTDirect`.
+
+
+---
+
+### From `CTDirect`
+
+
+## `DOCP`
+
+```@docs
+CTDirect.DOCP
+```
+
+
+## `DOCPFlags`
+
+```@docs
+CTDirect.DOCPFlags
+```
+
+
+## `DOCP_constraints!`
+
+```@docs
+CTDirect.DOCP_constraints!
+```
+
+
+## `DOCP_initial_guess`
+
+```@docs
+CTDirect.DOCP_initial_guess
+```
+
+
+## `DOCP_objective`
+
+```@docs
+CTDirect.DOCP_objective
+```
+
+
+## `DOCPbounds`
+
+```@docs
+CTDirect.DOCPbounds
+```
+
+
+## `DOCPdims`
+
+```@docs
+CTDirect.DOCPdims
+```
+
+
+## `DOCPtime`
+
+```@docs
+CTDirect.DOCPtime
+```
+
+
+## `build_OCP_solution`
+
+```@docs
+CTDirect.build_OCP_solution
+```
+
+
+## `build_bounds_block`
+
+```@docs
+CTDirect.build_bounds_block
+```
+
+
+## `constraints_bounds!`
+
+```@docs
+CTDirect.constraints_bounds!
+```
+
+
+## `disc_model`
+
+```@docs
+CTDirect.disc_model
+```
+
+
+## `get_time_grid`
+
+```@docs
+CTDirect.get_time_grid
+```
+
+
+## `get_time_grid_exa`
+
+```@docs
+CTDirect.get_time_grid_exa
+```
+
+
+## `is_empty`
+
+```@docs
+CTDirect.is_empty
+```
+
+
+## `ocp_model`
+
+```@docs
+CTDirect.ocp_model
+```
+
+
+## `variables_bounds!`
+
+```@docs
+CTDirect.variables_bounds!
+```
+
diff --git a/docs/src/api/core.md b/docs/src/api/core.md
new file mode 100644
index 00000000..e51413a7
--- /dev/null
+++ b/docs/src/api/core.md
@@ -0,0 +1,20 @@
+```@meta
+EditURL = nothing
+```
+
+# Private API
+
+This page lists **non-exported** (internal) symbols of `CTDirect`.
+
+
+---
+
+### From `CTDirect`
+
+
+## `Discretization`
+
+```@docs
+CTDirect.Discretization
+```
+
diff --git a/docs/src/api/discretization.md b/docs/src/api/discretization.md
new file mode 100644
index 00000000..42ef12c2
--- /dev/null
+++ b/docs/src/api/discretization.md
@@ -0,0 +1,132 @@
+```@meta
+EditURL = nothing
+```
+
+# Private API
+
+This page lists **non-exported** (internal) symbols of `CTDirect`.
+
+
+---
+
+### From `CTDirect`
+
+
+## `DOCP_Hessian_pattern`
+
+```@docs
+CTDirect.DOCP_Hessian_pattern
+```
+
+
+## `DOCP_Jacobian_pattern`
+
+```@docs
+CTDirect.DOCP_Jacobian_pattern
+```
+
+
+## `Gauss_Legendre_1`
+
+```@docs
+CTDirect.Gauss_Legendre_1
+```
+
+
+## `Gauss_Legendre_2`
+
+```@docs
+CTDirect.Gauss_Legendre_2
+```
+
+
+## `Gauss_Legendre_3`
+
+```@docs
+CTDirect.Gauss_Legendre_3
+```
+
+
+## `IRK_dims`
+
+```@docs
+CTDirect.IRK_dims
+```
+
+
+## `add_nonzero_block!`
+
+```@docs
+CTDirect.add_nonzero_block!
+```
+
+
+## `get_OCP_control_at_time_step`
+
+```@docs
+CTDirect.get_OCP_control_at_time_step
+```
+
+
+## `get_OCP_state_at_time_step`
+
+```@docs
+CTDirect.get_OCP_state_at_time_step
+```
+
+
+## `get_OCP_variable`
+
+```@docs
+CTDirect.get_OCP_variable
+```
+
+
+## `get_stagevars_at_time_step`
+
+```@docs
+CTDirect.get_stagevars_at_time_step
+```
+
+
+## `runningCost`
+
+```@docs
+CTDirect.runningCost
+```
+
+
+## `setStepConstraints!`
+
+```@docs
+CTDirect.setStepConstraints!
+```
+
+
+## `setWorkArray`
+
+```@docs
+CTDirect.setWorkArray
+```
+
+
+## `set_control_at_time_step!`
+
+```@docs
+CTDirect.set_control_at_time_step!
+```
+
+
+## `set_optim_variable!`
+
+```@docs
+CTDirect.set_optim_variable!
+```
+
+
+## `set_state_at_time_step!`
+
+```@docs
+CTDirect.set_state_at_time_step!
+```
+
diff --git a/docs/src/collocation.md b/docs/src/collocation.md
deleted file mode 100644
index 3a1396b8..00000000
--- a/docs/src/collocation.md
+++ /dev/null
@@ -1,17 +0,0 @@
-# Solution
-
-## Index
-
-```@index
-Pages   = ["collocation.md"]
-Modules = [CTDirect]
-Order = [:module, :constant, :type, :function, :macro]
-```
-
-## Documentation
-
-```@autodocs
-Pages = ["collocation.jl"]
-Modules = [CTDirect]
-Order = [:module, :constant, :type, :function, :macro]
-```
diff --git a/docs/src/collocation_core.md b/docs/src/collocation_core.md
deleted file mode 100644
index a54390ec..00000000
--- a/docs/src/collocation_core.md
+++ /dev/null
@@ -1,17 +0,0 @@
-# Solution
-
-## Index
-
-```@index
-Pages   = ["collocation_core.md"]
-Modules = [CTDirect]
-Order = [:module, :constant, :type, :function, :macro]
-```
-
-## Documentation
-
-```@autodocs
-Pages = ["collocation_core.jl"]
-Modules = [CTDirect]
-Order = [:module, :constant, :type, :function, :macro]
-```
diff --git a/docs/src/collocation_functions.md b/docs/src/collocation_functions.md
deleted file mode 100644
index e0754d30..00000000
--- a/docs/src/collocation_functions.md
+++ /dev/null
@@ -1,17 +0,0 @@
-# Solution
-
-## Index
-
-```@index
-Pages   = ["collocation_functions.md"]
-Modules = [CTDirect]
-Order = [:module, :constant, :type, :function, :macro]
-```
-
-## Documentation
-
-```@autodocs
-Pages = ["collocation_functions.jl"]
-Modules = [CTDirect]
-Order = [:module, :constant, :type, :function, :macro]
-```
diff --git a/docs/src/collocation_variables.md b/docs/src/collocation_variables.md
deleted file mode 100644
index dfb300a6..00000000
--- a/docs/src/collocation_variables.md
+++ /dev/null
@@ -1,17 +0,0 @@
-# Solution
-
-## Index
-
-```@index
-Pages   = ["collocation_variables.md"]
-Modules = [CTDirect]
-Order = [:module, :constant, :type, :function, :macro]
-```
-
-## Documentation
-
-```@autodocs
-Pages = ["collocation_variables.jl"]
-Modules = [CTDirect]
-Order = [:module, :constant, :type, :function, :macro]
-```
diff --git a/docs/src/common.md b/docs/src/common.md
deleted file mode 100644
index 54db7d1c..00000000
--- a/docs/src/common.md
+++ /dev/null
@@ -1,17 +0,0 @@
-# Common
-
-## Index
-
-```@index
-Pages   = ["common.md"]
-Modules = [CTDirect]
-Order = [:module, :constant, :type, :function, :macro]
-```
-
-## Documentation
-
-```@autodocs
-Pages = ["common.jl"]
-Modules = [CTDirect]
-Order = [:module, :constant, :type, :function, :macro]
-```
\ No newline at end of file
diff --git a/docs/src/docp.md b/docs/src/docp.md
deleted file mode 100644
index b0439ca4..00000000
--- a/docs/src/docp.md
+++ /dev/null
@@ -1,17 +0,0 @@
-# DOCP
-
-## Index
-
-```@index
-Pages   = ["docp.md"]
-Modules = [CTDirect]
-Order = [:module, :constant, :type, :function, :macro]
-```
-
-## Documentation
-
-```@autodocs
-Pages = ["docp.jl"]
-Modules = [CTDirect]
-Order = [:module, :constant, :type, :function, :macro]
-```
\ No newline at end of file
diff --git a/docs/src/euler.md b/docs/src/euler.md
deleted file mode 100644
index a431a7df..00000000
--- a/docs/src/euler.md
+++ /dev/null
@@ -1,17 +0,0 @@
-# Euler
-
-## Index
-
-```@index
-Pages   = ["euler.md"]
-Modules = [CTDirect]
-Order = [:module, :constant, :type, :function, :macro]
-```
-
-## Documentation
-
-```@autodocs
-Pages = ["euler.jl"]
-Modules = [CTDirect]
-Order = [:module, :constant, :type, :function, :macro]
-```
\ No newline at end of file
diff --git a/docs/src/index.md b/docs/src/index.md
index d4941a6e..8e04086b 100644
--- a/docs/src/index.md
+++ b/docs/src/index.md
@@ -3,19 +3,13 @@
 ```@meta
 CurrentModule =  CTDirect
 ```
+
 The `CTDirect.jl` package is part of the [control-toolbox ecosystem](https://github.com/control-toolbox).
 
 The root package is [OptimalControl.jl](https://github.com/control-toolbox/OptimalControl.jl) which aims to provide tools to model and solve optimal control problems with ordinary differential equations by direct and indirect methods, both on CPU and GPU.
 
 To install a package from the control-toolbox ecosystem, please visit the [installation page](https://github.com/control-toolbox#installation).
 
-## API Documentation
-
-```@contents
-Pages = Main.API_PAGES
-Depth = 1
-```
-
 ## Brief Overview
 
 An optimal control problem with fixed initial and final times, denoted (OCP), can be described as minimising the cost functional
diff --git a/docs/src/irk.md b/docs/src/irk.md
deleted file mode 100644
index c60b5703..00000000
--- a/docs/src/irk.md
+++ /dev/null
@@ -1,17 +0,0 @@
-# IRK
-
-## Index
-
-```@index
-Pages   = ["irk.md"]
-Modules = [CTDirect]
-Order = [:module, :constant, :type, :function, :macro]
-```
-
-## Documentation
-
-```@autodocs
-Pages = ["irk.jl"]
-Modules = [CTDirect]
-Order = [:module, :constant, :type, :function, :macro]
-```
\ No newline at end of file
diff --git a/docs/src/midpoint.md b/docs/src/midpoint.md
deleted file mode 100644
index e98824a6..00000000
--- a/docs/src/midpoint.md
+++ /dev/null
@@ -1,17 +0,0 @@
-# Midpoint
-
-## Index
-
-```@index
-Pages   = ["midpoint.md"]
-Modules = [CTDirect]
-Order = [:module, :constant, :type, :function, :macro]
-```
-
-## Documentation
-
-```@autodocs
-Pages = ["midpoint.jl"]
-Modules = [CTDirect]
-Order = [:module, :constant, :type, :function, :macro]
-```
\ No newline at end of file
diff --git a/docs/src/trapeze.md b/docs/src/trapeze.md
deleted file mode 100644
index a23e7151..00000000
--- a/docs/src/trapeze.md
+++ /dev/null
@@ -1,17 +0,0 @@
-# Trapeze
-
-## Index
-
-```@index
-Pages   = ["trapeze.md"]
-Modules = [CTDirect]
-Order = [:module, :constant, :type, :function, :macro]
-```
-
-## Documentation
-
-```@autodocs
-Pages = ["trapeze.jl"]
-Modules = [CTDirect]
-Order = [:module, :constant, :type, :function, :macro]
-```
\ No newline at end of file
diff --git a/src/CTDirect.jl b/src/CTDirect.jl
index f48da33a..c60bc4dd 100644
--- a/src/CTDirect.jl
+++ b/src/CTDirect.jl
@@ -12,6 +12,7 @@ import SparseArrays
 
 # ----------------------------------------------------------------------
 # TYPES
+# ----------------------------------------------------------------------
 const AbstractModel = CTModels.AbstractModel
 
 # ---------------------------------------------------------------------------

From 97cf84979ecc93109cde7fcf1c15ef716ce22dfa Mon Sep 17 00:00:00 2001
From: Olivier Cots <olivier.cots@irit.fr>
Date: Fri, 6 Mar 2026 08:56:29 +0100
Subject: [PATCH 3/3] foo

---
 docs/Project.toml              |   1 -
 docs/src/api/collocation.md    | 132 ---------------------------------
 docs/src/api/core.md           |  20 -----
 docs/src/api/discretization.md | 132 ---------------------------------
 4 files changed, 285 deletions(-)
 delete mode 100644 docs/src/api/collocation.md
 delete mode 100644 docs/src/api/core.md
 delete mode 100644 docs/src/api/discretization.md

diff --git a/docs/Project.toml b/docs/Project.toml
index ad7b2925..b5cfae0b 100644
--- a/docs/Project.toml
+++ b/docs/Project.toml
@@ -1,6 +1,5 @@
 [deps]
 CTBase = "54762871-cc72-4466-b8e8-f6c8b58076cd"
-CTDirect = "790bbbee-bee9-49ee-8912-a9de031322d5"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterMermaid = "a078cd44-4d9c-4618-b545-3ab9d77f9177"
 Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"
diff --git a/docs/src/api/collocation.md b/docs/src/api/collocation.md
deleted file mode 100644
index f693000e..00000000
--- a/docs/src/api/collocation.md
+++ /dev/null
@@ -1,132 +0,0 @@
-```@meta
-EditURL = nothing
-```
-
-# Private API
-
-This page lists **non-exported** (internal) symbols of `CTDirect`.
-
-
----
-
-### From `CTDirect`
-
-
-## `DOCP`
-
-```@docs
-CTDirect.DOCP
-```
-
-
-## `DOCPFlags`
-
-```@docs
-CTDirect.DOCPFlags
-```
-
-
-## `DOCP_constraints!`
-
-```@docs
-CTDirect.DOCP_constraints!
-```
-
-
-## `DOCP_initial_guess`
-
-```@docs
-CTDirect.DOCP_initial_guess
-```
-
-
-## `DOCP_objective`
-
-```@docs
-CTDirect.DOCP_objective
-```
-
-
-## `DOCPbounds`
-
-```@docs
-CTDirect.DOCPbounds
-```
-
-
-## `DOCPdims`
-
-```@docs
-CTDirect.DOCPdims
-```
-
-
-## `DOCPtime`
-
-```@docs
-CTDirect.DOCPtime
-```
-
-
-## `build_OCP_solution`
-
-```@docs
-CTDirect.build_OCP_solution
-```
-
-
-## `build_bounds_block`
-
-```@docs
-CTDirect.build_bounds_block
-```
-
-
-## `constraints_bounds!`
-
-```@docs
-CTDirect.constraints_bounds!
-```
-
-
-## `disc_model`
-
-```@docs
-CTDirect.disc_model
-```
-
-
-## `get_time_grid`
-
-```@docs
-CTDirect.get_time_grid
-```
-
-
-## `get_time_grid_exa`
-
-```@docs
-CTDirect.get_time_grid_exa
-```
-
-
-## `is_empty`
-
-```@docs
-CTDirect.is_empty
-```
-
-
-## `ocp_model`
-
-```@docs
-CTDirect.ocp_model
-```
-
-
-## `variables_bounds!`
-
-```@docs
-CTDirect.variables_bounds!
-```
-
diff --git a/docs/src/api/core.md b/docs/src/api/core.md
deleted file mode 100644
index e51413a7..00000000
--- a/docs/src/api/core.md
+++ /dev/null
@@ -1,20 +0,0 @@
-```@meta
-EditURL = nothing
-```
-
-# Private API
-
-This page lists **non-exported** (internal) symbols of `CTDirect`.
-
-
----
-
-### From `CTDirect`
-
-
-## `Discretization`
-
-```@docs
-CTDirect.Discretization
-```
-
diff --git a/docs/src/api/discretization.md b/docs/src/api/discretization.md
deleted file mode 100644
index 42ef12c2..00000000
--- a/docs/src/api/discretization.md
+++ /dev/null
@@ -1,132 +0,0 @@
-```@meta
-EditURL = nothing
-```
-
-# Private API
-
-This page lists **non-exported** (internal) symbols of `CTDirect`.
-
-
----
-
-### From `CTDirect`
-
-
-## `DOCP_Hessian_pattern`
-
-```@docs
-CTDirect.DOCP_Hessian_pattern
-```
-
-
-## `DOCP_Jacobian_pattern`
-
-```@docs
-CTDirect.DOCP_Jacobian_pattern
-```
-
-
-## `Gauss_Legendre_1`
-
-```@docs
-CTDirect.Gauss_Legendre_1
-```
-
-
-## `Gauss_Legendre_2`
-
-```@docs
-CTDirect.Gauss_Legendre_2
-```
-
-
-## `Gauss_Legendre_3`
-
-```@docs
-CTDirect.Gauss_Legendre_3
-```
-
-
-## `IRK_dims`
-
-```@docs
-CTDirect.IRK_dims
-```
-
-
-## `add_nonzero_block!`
-
-```@docs
-CTDirect.add_nonzero_block!
-```
-
-
-## `get_OCP_control_at_time_step`
-
-```@docs
-CTDirect.get_OCP_control_at_time_step
-```
-
-
-## `get_OCP_state_at_time_step`
-
-```@docs
-CTDirect.get_OCP_state_at_time_step
-```
-
-
-## `get_OCP_variable`
-
-```@docs
-CTDirect.get_OCP_variable
-```
-
-
-## `get_stagevars_at_time_step`
-
-```@docs
-CTDirect.get_stagevars_at_time_step
-```
-
-
-## `runningCost`
-
-```@docs
-CTDirect.runningCost
-```
-
-
-## `setStepConstraints!`
-
-```@docs
-CTDirect.setStepConstraints!
-```
-
-
-## `setWorkArray`
-
-```@docs
-CTDirect.setWorkArray
-```
-
-
-## `set_control_at_time_step!`
-
-```@docs
-CTDirect.set_control_at_time_step!
-```
-
-
-## `set_optim_variable!`
-
-```@docs
-CTDirect.set_optim_variable!
-```
-
-
-## `set_state_at_time_step!`
-
-```@docs
-CTDirect.set_state_at_time_step!
-```
-