Skip to content

Commit 71718db

Browse files
ocotsocots
authored
Merge pull request #719 from control-toolbox/documentation
Documentation
2 parents 53d1ff6 + 7d29982 commit 71718db

43 files changed

Lines changed: 7653 additions & 159 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.save/docs/src/manual-model.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -106,7 +106,7 @@ Each field can be accessed directly (`ocp.times`, etc) or by a getter:
106106
- [`control`](@ref)
107107
- [`variable`](@ref)
108108
- [`dynamics`](@ref)
109-
- [`objective`](@ref)
109+
- `objective`
110110
- [`constraints`](@ref)
111111
- [`definition`](@ref)
112112
- [`get_build_examodel`](@ref)

‎docs/Project.toml‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
[deps]
2+
ADNLPModels = "54578032-b7ea-4c30-94aa-7cbd1cce6c9a"
3+
CTBase = "54762871-cc72-4466-b8e8-f6c8b58076cd"
4+
CTDirect = "790bbbee-bee9-49ee-8912-a9de031322d5"
5+
CTFlows = "1c39547c-7794-42f7-af83-d98194f657c2"
6+
CTModels = "34c4fa32-2049-4079-8329-de33c2a22e2d"
7+
CTParser = "32681960-a1b1-40db-9bff-a1ca817385d1"
8+
CTSolvers = "d3e8d392-8e4b-4d9b-8e92-d7d4e3650ef6"
9+
CommonSolve = "38540f10-b2f7-11e9-35d8-d573e4eb0ff2"
10+
DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
11+
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
12+
DocumenterInterLinks = "d12716ef-a0f6-4df4-a9f1-a5a34e75c656"
13+
DocumenterMermaid = "a078cd44-4d9c-4618-b545-3ab9d77f9177"
14+
ExaModels = "1037b233-b668-4ce9-9b63-f9f681f55dd2"
15+
JLD2 = "033835bb-8acc-5ee8-8aae-3f567f8a3819"
16+
JSON3 = "0f8b85d8-7281-11e9-16c2-39a750bddbf1"
17+
MadNCL = "434a0bcb-5a7c-42b2-a9d3-9e3f760e7af0"
18+
MadNLP = "2621e9c9-9eb4-46b1-8089-e8c72242dfb6"
19+
MarkdownAST = "d0879d2d-cac2-40c8-9cee-1863dc0c7391"
20+
NLPModelsIpopt = "f4238b75-b362-5c4c-b852-0801c9a21d71"
21+
NLPModelsKnitro = "bec4dd0d-7755-52d5-9a02-22f0ffc7efcb"
22+
NonlinearSolve = "8913a72c-1f9b-4ce2-8d82-65094dcecaec"
23+
OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed"
24+
Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
25+
26+
[compat]
27+
ADNLPModels = "0.8"
28+
CTBase = "0.18"
29+
CTDirect = "1"
30+
CTFlows = "0.8"
31+
CTModels = "0.9"
32+
CTParser = "0.8"
33+
CTSolvers = "0.4"
34+
CommonSolve = "0.2"
35+
DataFrames = "1"
36+
Documenter = "1"
37+
DocumenterInterLinks = "1"
38+
DocumenterMermaid = "0.2"
39+
ExaModels = "0.9"
40+
JLD2 = "0.6"
41+
JSON3 = "1"
42+
MadNCL = "0.2"
43+
MadNLP = "0.9"
44+
MarkdownAST = "0.1"
45+
NLPModelsIpopt = "0.11"
46+
NLPModelsKnitro = "0.10"
47+
NonlinearSolve = "4"
48+
OrdinaryDiffEq = "6"
49+
Plots = "1"
50+
julia = "1.10"

‎docs/api_reference.jl‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# ==============================================================================
2+
# OptimalControl API Reference Generator
3+
# ==============================================================================
4+
#
5+
# This file generates the API reference documentation for OptimalControl.
6+
# It uses CTBase.automatic_reference_documentation to scan source files
7+
# and generate documentation pages.
8+
#
9+
# ==============================================================================
10+
11+
"""
12+
generate_api_reference(src_dir::String, ext_dir::String)
13+
14+
Generate the API reference documentation for OptimalControl.
15+
Returns the list of pages.
16+
"""
17+
function generate_api_reference(src_dir::String, ext_dir::String)
18+
# Helper to build absolute paths
19+
src(files...) = [abspath(joinpath(src_dir, f)) for f in files]
20+
ext(files...) = [abspath(joinpath(ext_dir, f)) for f in files]
21+
22+
# Symbols to exclude from documentation
23+
EXCLUDE_SYMBOLS = Symbol[:include, :eval]
24+
25+
pages = [
26+
27+
CTBase.automatic_reference_documentation(;
28+
subdirectory="api",
29+
primary_modules=[
30+
OptimalControl => src(
31+
joinpath("helpers", "component_checks.jl"),
32+
joinpath("helpers", "component_completion.jl"),
33+
joinpath("helpers", "descriptive_routing.jl"),
34+
joinpath("helpers", "kwarg_extraction.jl"),
35+
joinpath("helpers", "methods.jl"),
36+
joinpath("helpers", "print.jl"),
37+
joinpath("helpers", "registry.jl"),
38+
joinpath("helpers", "strategy_builders.jl"),
39+
joinpath("solve", "canonical.jl"),
40+
joinpath("solve", "descriptive.jl"),
41+
joinpath("solve", "dispatch.jl"),
42+
joinpath("solve", "explicit.jl"),
43+
joinpath("solve", "mode.jl"),
44+
joinpath("solve", "mode_detection.jl"),
45+
),
46+
],
47+
external_modules_to_document=[CTBase, CTModels, CTSolvers],
48+
exclude=EXCLUDE_SYMBOLS,
49+
public=false,
50+
private=true,
51+
title="Private",
52+
title_in_menu="Private",
53+
filename="private",
54+
),
55+
56+
]
57+
58+
return pages
59+
end
60+
61+
"""
62+
with_api_reference(f::Function, src_dir::String, ext_dir::String)
63+
64+
Generates the API reference, executes `f(pages)`, and cleans up generated files.
65+
"""
66+
function with_api_reference(f::Function, src_dir::String, ext_dir::String)
67+
pages = generate_api_reference(src_dir, ext_dir)
68+
try
69+
f(pages)
70+
finally
71+
# Clean up generated files
72+
docs_src = abspath(joinpath(@__DIR__, "src"))
73+
_cleanup_pages(docs_src, pages)
74+
end
75+
end
76+
77+
function _cleanup_pages(docs_src::String, pages)
78+
for p in pages
79+
val = last(p)
80+
if val isa AbstractString
81+
fname = endswith(val, ".md") ? val : val * ".md"
82+
full_path = joinpath(docs_src, fname)
83+
if isfile(full_path)
84+
rm(full_path)
85+
println("Removed temporary API doc: $full_path")
86+
end
87+
elseif val isa AbstractVector
88+
_cleanup_pages(docs_src, val)
89+
end
90+
end
91+
end

‎docs/doc.jl‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
#!/usr/bin/env julia
2+
3+
"""
4+
Documentation Generation Script for OptimalControl.jl
5+
6+
This script generates the documentation for OptimalControl.jl and then removes
7+
OptimalControl from the docs/Project.toml to keep it clean.
8+
9+
Usage (from any directory):
10+
julia docs/doc.jl
11+
# OR
12+
julia --project=. docs/doc.jl
13+
# OR
14+
julia --project=docs docs/doc.jl
15+
16+
The script will:
17+
1. Activate the docs environment
18+
2. Add OptimalControl as a development dependency in docs environment
19+
3. Generate the documentation using docs/make.jl
20+
4. Remove OptimalControl from docs/Project.toml
21+
5. Clean up the docs environment
22+
"""
23+
24+
using Pkg
25+
26+
println("🚀 Starting documentation generation for OptimalControl.jl...")
27+
28+
# Step 0: Activate docs environment (works from any directory)
29+
docs_dir = joinpath(@__DIR__)
30+
println("📁 Activating docs environment at: $docs_dir")
31+
Pkg.activate(docs_dir)
32+
33+
# Step 1: Add OptimalControl as development dependency
34+
println("📦 Adding OptimalControl as development dependency...")
35+
# Get the project root (parent of docs directory)
36+
project_root = dirname(docs_dir)
37+
Pkg.develop(; path=project_root)
38+
39+
# Step 2: Generate documentation
40+
println("📚 Building documentation...")
41+
include(joinpath(docs_dir, "make.jl"))
42+
43+
# Step 3: Remove OptimalControl from docs environment
44+
println("🧹 Cleaning up docs environment...")
45+
Pkg.rm("OptimalControl")
46+
47+
println("✅ Documentation generated successfully!")
48+
println("📖 Documentation available at: $(joinpath(docs_dir, "build", "index.html"))")
49+
println("🗂️ OptimalControl removed from docs/Project.toml")

0 commit comments

Comments
 (0)