refactor: clean up codebase and documentation

Project.toml

@@ -1,20 +1,17 @@
 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]
 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,31 +21,33 @@ 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"
 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"]

docs/Project.toml

@@ -1,17 +1,13 @@
 [deps]
-ADNLPModels = "54578032-b7ea-4c30-94aa-7cbd1cce6c9a"
+CTBase = "54762871-cc72-4466-b8e8-f6c8b58076cd"
 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"
+Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"
+MarkdownAST = "d0879d2d-cac2-40c8-9cee-1863dc0c7391"
 
 [compat]
-ADNLPModels = "0.8"
+CTBase = "0.18"
 Documenter = "1"
 DocumenterMermaid = "0.2"
-ExaModels = "0.9"
-MadNLP = "0.8"
-NLPModelsIpopt = "0.11"
-MadNLPMumps = "0.5"
+Markdown = "1"
+MarkdownAST = "0.1"

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

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")

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")