Add tutorial with Literate + Binder setup

Project.toml

@@ -38,6 +38,7 @@ Documenter = "1.17.0"
 ExaModels = "0.9"
 ForwardDiff = "0.10, 1.0"
 LinearAlgebra = "1"
+Literate = "2"
 MadNCL = "0.2"
 MadNLP = "0.9"
 MadNLPGPU = "0.8"
@@ -59,6 +60,7 @@ BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
 CUDA = "052768ef-5323-5732-b1bb-66c8b64840ba"
 DifferentiationInterface = "a0c0ee7d-e4b9-4e03-894e-1c5f64a51d63"
 ForwardDiff = "f6369f11-7733-5829-9624-2563aa707210"
+Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 MadNCL = "434a0bcb-5a7c-42b2-a9d3-9e3f760e7af0"
 MadNLP = "2621e9c9-9eb4-46b1-8089-e8c72242dfb6"

binder/Project.toml

@@ -0,0 +1,9 @@
+[deps]
+BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
+CUDA = "052768ef-5323-5732-b1bb-66c8b64840ba"
+MadNLP = "2621e9c9-9eb4-46b1-8089-e8c72242dfb6"
+MadNLPGPU = "d72a61cc-809d-412f-99be-fd81f4b8a598"
+NLPModelsIpopt = "f4238b75-b362-5c4c-b852-0801c9a21d71"
+NonlinearSolve = "8913a72c-1f9b-4ce2-8d82-65094dcecaec"
+OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed"
+Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"

binder/apt.txt

@@ -0,0 +1,4 @@
+build-essential
+libgmp-dev
+libblas-dev
+liblapack-dev

binder/postBuild

@@ -0,0 +1,5 @@
+#!/bin/bash
+set -e
+
+# Install OptimalControl.jl from the repo root into the Binder environment
+julia --project=binder -e 'using Pkg; Pkg.develop(path="."); Pkg.precompile()'

docs/Project.toml

@@ -1,5 +1,6 @@
 [deps]
 ADNLPModels = "54578032-b7ea-4c30-94aa-7cbd1cce6c9a"
+BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
 CTBase = "54762871-cc72-4466-b8e8-f6c8b58076cd"
 CTDirect = "790bbbee-bee9-49ee-8912-a9de031322d5"
 CTFlows = "1c39547c-7794-42f7-af83-d98194f657c2"
@@ -15,6 +16,7 @@ DocumenterMermaid = "a078cd44-4d9c-4618-b545-3ab9d77f9177"
 ExaModels = "1037b233-b668-4ce9-9b63-f9f681f55dd2"
 JLD2 = "033835bb-8acc-5ee8-8aae-3f567f8a3819"
 JSON3 = "0f8b85d8-7281-11e9-16c2-39a750bddbf1"
+Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
 MadNCL = "434a0bcb-5a7c-42b2-a9d3-9e3f760e7af0"
 MadNLP = "2621e9c9-9eb4-46b1-8089-e8c72242dfb6"
 MadNLPGPU = "d72a61cc-809d-412f-99be-fd81f4b8a598"
@@ -28,10 +30,11 @@ UnoSolver = "1baa60ac-02f7-4b39-a7a8-2f4f58486b05"
 
 [compat]
 ADNLPModels = "0.8"
-CTBase = "0.18"
+BenchmarkTools = "1"
+CTBase = "=0.18.8"
 CTDirect = "1"
 CTFlows = "0.8"
-CTModels = "0.10"
+CTModels = "=0.10.1"
 CTParser = "0.8"
 CTSolvers = "0.4"
 CUDA = "5"
@@ -43,6 +46,7 @@ DocumenterMermaid = "0.2"
 ExaModels = "0.9"
 JLD2 = "0.6"
 JSON3 = "1"
+Literate = "2"
 MadNCL = "0.2"
 MadNLP = "0.9"
 MadNLPGPU = "0.8"

docs/make.jl

@@ -153,7 +153,7 @@ cp(
 Draft = false
 ```
 =#
-draft = false  # Draft mode: if true, @example blocks in markdown are not executed
+draft = false  # Draft mode: skip @example execution globally; tutorial overrides below
 
 # ═══════════════════════════════════════════════════════════════════════════════
 # Load extensions
@@ -201,6 +201,29 @@ function Logging.handle_message(
 end
 global_logger(ExampleSizeThresholdFilter(global_logger()))
 
+# ═══════════════════════════════════════════════════════════════════════════════
+# Literate: generate tutorial.md, tutorial.ipynb, tutorial.jl
+# ═══════════════════════════════════════════════════════════════════════════════
+using Literate
+
+LITERATE_DIR = joinpath(@__DIR__, "src-literate")
+MD_OUTPUT    = joinpath(@__DIR__, "src")
+NB_OUTPUT    = joinpath(@__DIR__, "src", "notebooks")
+JL_OUTPUT    = joinpath(@__DIR__, "src", "scripts")
+mkpath(NB_OUTPUT)
+mkpath(JL_OUTPUT)
+
+for file in ["tutorial.jl"]
+    INPUT = joinpath(LITERATE_DIR, file)
+    # Inject @meta Draft=false so the tutorial executes even with global draft=true
+    function tutorial_postprocess(content)
+        return "```@meta\nDraft = false\n```\n\n" * content
+    end
+    Literate.markdown(INPUT, MD_OUTPUT; documenter=true, postprocess=tutorial_postprocess)
+    Literate.notebook(INPUT, NB_OUTPUT; execute=false)
+    Literate.script(INPUT, JL_OUTPUT)
+end
+
 # ═══════════════════════════════════════════════════════════════════════════════
 # Build documentation
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -229,11 +252,13 @@ with_api_reference(src_dir, ext_dir) do api_pages
                 joinpath("api", "private.md"),
                 joinpath("api", "public.md"),
                 "manual-macro-free.md",
+                "tutorial.md",
             ],
         ),
         pages=[
             "Introduction" => "index.md",
-            "Basic Examples" => [
+            "Guided tour" => "tutorial.md",
+            "Examples" => [
                 "Energy minimisation" => "example-double-integrator-energy.md",
                 "Time mininimisation" => "example-double-integrator-time.md",
                 "Control-free problems" => "example-control-free.md",