Skip to content

Commit 117d607

Browse files
ocotsocots
committed
docs: comprehensive docstring review and documentation system
- Updated all docstrings across solve architecture (dispatch, explicit, descriptive, canonical) - Enhanced helper function docstrings with type annotations and detailed Notes sections - Added comprehensive module docstring for OptimalControl.jl - Fixed alias references (removed invalid 'i' alias, kept only 'init') - Added proper cross-references using @ref and @extref - Created documentation build system with API reference generation - Added public API documentation page - Ensured consistency with documentation standards - Improved examples and added architectural context
1 parent 2f7c853 commit 117d607

24 files changed

Lines changed: 3715 additions & 154 deletions

‎docs/Project.toml‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
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+
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
11+
DocumenterInterLinks = "d12716ef-a0f6-4df4-a9f1-a5a34e75c656"
12+
DocumenterMermaid = "a078cd44-4d9c-4618-b545-3ab9d77f9177"
13+
ExaModels = "1037b233-b668-4ce9-9b63-f9f681f55dd2"
14+
JLD2 = "033835bb-8acc-5ee8-8aae-3f567f8a3819"
15+
JSON3 = "0f8b85d8-7281-11e9-16c2-39a750bddbf1"
16+
MadNCL = "434a0bcb-5a7c-42b2-a9d3-9e3f760e7af0"
17+
MadNLP = "2621e9c9-9eb4-46b1-8089-e8c72242dfb6"
18+
MarkdownAST = "d0879d2d-cac2-40c8-9cee-1863dc0c7391"
19+
NLPModelsIpopt = "f4238b75-b362-5c4c-b852-0801c9a21d71"
20+
NLPModelsKnitro = "bec4dd0d-7755-52d5-9a02-22f0ffc7efcb"
21+
OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed"
22+
Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
23+
24+
[compat]
25+
ADNLPModels = "0.8"
26+
CTBase = "0.18"
27+
CTDirect = "1"
28+
CTFlows = "0.8"
29+
CTModels = "0.9"
30+
CTParser = "0.8"
31+
CTSolvers = "0.4"
32+
CommonSolve = "0.2"
33+
Documenter = "1"
34+
DocumenterInterLinks = "1"
35+
DocumenterMermaid = "0.2"
36+
ExaModels = "0.9"
37+
JLD2 = "0.6"
38+
JSON3 = "1"
39+
MadNCL = "0.2"
40+
MadNLP = "0.9"
41+
MarkdownAST = "0.1"
42+
NLPModelsIpopt = "0.11"
43+
NLPModelsKnitro = "0.10"
44+
OrdinaryDiffEq = "6"
45+
Plots = "1"
46+
julia = "1.10"

‎docs/api_reference.jl‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
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+
# # Main Module
58+
# # ───────────────────────────────────────────────────────────────────
59+
# CTBase.automatic_reference_documentation(;
60+
# subdirectory="api",
61+
# primary_modules=[
62+
# OptimalControl => src(
63+
# "OptimalControl.jl",
64+
# ),
65+
# ],
66+
# external_modules_to_document=[CommonSolve, CTBase, CTDirect, CTFlows, CTModels, CTParser, CTSolvers],
67+
# exclude=EXCLUDE_SYMBOLS,
68+
# public=true,
69+
# private=true,
70+
# title="Main Module",
71+
# title_in_menu="Main Module",
72+
# filename="main_module",
73+
# ),
74+
75+
]
76+
77+
return pages
78+
end
79+
80+
"""
81+
with_api_reference(f::Function, src_dir::String, ext_dir::String)
82+
83+
Generates the API reference, executes `f(pages)`, and cleans up generated files.
84+
"""
85+
function with_api_reference(f::Function, src_dir::String, ext_dir::String)
86+
pages = generate_api_reference(src_dir, ext_dir)
87+
try
88+
f(pages)
89+
finally
90+
# Clean up generated files
91+
docs_src = abspath(joinpath(@__DIR__, "src"))
92+
_cleanup_pages(docs_src, pages)
93+
end
94+
end
95+
96+
function _cleanup_pages(docs_src::String, pages)
97+
for p in pages
98+
val = last(p)
99+
if val isa AbstractString
100+
fname = endswith(val, ".md") ? val : val * ".md"
101+
full_path = joinpath(docs_src, fname)
102+
if isfile(full_path)
103+
rm(full_path)
104+
println("Removed temporary API doc: $full_path")
105+
end
106+
elseif val isa AbstractVector
107+
_cleanup_pages(docs_src, val)
108+
end
109+
end
110+
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)