Maintenance v0.17.2 Planning

.gitignore

@@ -26,6 +26,10 @@ docs/site/
 # environment.
 Manifest.toml
 
+# Test outputs
+test/solution.jld2
+test/solution.json
+
 #
 reports/
 profiling/

docs/api_reference.jl

@@ -0,0 +1,295 @@
+# ==============================================================================
+# CTModels API Reference Generator
+# ==============================================================================
+#
+# This module provides functions to generate API reference documentation
+# for CTModels.jl, following the pattern established in CTBase.jl.
+#
+# ==============================================================================
+
+"""
+    generate_api_reference(src_dir::String, ext_dir::String)
+
+Generate the API reference documentation for CTModels.
+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 (auto-generated by @with_kw, etc.)
+    EXCLUDE_SYMBOLS = Symbol[
+        :include,
+        :eval,
+        Symbol("@pack_PreModel"),
+        Symbol("@pack_PreModel!"),
+        Symbol("@unpack_PreModel"),
+        :is_empty,
+    ]
+
+    pages = [
+        # ───────────────────────────────────────────────────────────────────
+        # Main module
+        # ───────────────────────────────────────────────────────────────────
+        CTBase.automatic_reference_documentation(;
+            subdirectory=".",
+            primary_modules=[CTModels => src("CTModels.jl")],
+            exclude=EXCLUDE_SYMBOLS,
+            public=false,
+            private=true,
+            title="CTModels",
+            title_in_menu="CTModels",
+            filename="ctmodels",
+        ),
+        # ───────────────────────────────────────────────────────────────────
+        # Core: Types
+        # ───────────────────────────────────────────────────────────────────
+        CTBase.automatic_reference_documentation(;
+            subdirectory=".",
+            primary_modules=[
+                CTModels => src(
+                    "core/types.jl",
+                    "core/types/ocp_model.jl",
+                    "core/types/ocp_components.jl",
+                    "core/types/ocp_solution.jl",
+                    "core/types/initial_guess.jl",
+                    "core/types/nlp.jl",
+                ),
+            ],
+            exclude=EXCLUDE_SYMBOLS,
+            public=false,
+            private=true,
+            title="Types",
+            title_in_menu="Types",
+            filename="types",
+        ),
+        # ───────────────────────────────────────────────────────────────────
+        # Core: Default & Utils
+        # ───────────────────────────────────────────────────────────────────
+        CTBase.automatic_reference_documentation(;
+            subdirectory=".",
+            primary_modules=[CTModels => src("core/default.jl", "core/utils.jl")],
+            exclude=EXCLUDE_SYMBOLS,
+            public=false,
+            private=true,
+            title="Default & Utils",
+            title_in_menu="Default & Utils",
+            filename="default_utils",
+        ),
+        # ───────────────────────────────────────────────────────────────────
+        # OCP: Model (model, definition, time_dependence)
+        # ───────────────────────────────────────────────────────────────────
+        CTBase.automatic_reference_documentation(;
+            subdirectory=".",
+            primary_modules=[
+                CTModels => src(
+                    "ocp/model.jl",
+                    "ocp/definition.jl",
+                    "ocp/time_dependence.jl",
+                ),
+            ],
+            exclude=EXCLUDE_SYMBOLS,
+            public=false,
+            private=true,
+            title="Model",
+            title_in_menu="Model",
+            filename="model",
+        ),
+        # ───────────────────────────────────────────────────────────────────
+        # OCP: Times
+        # ───────────────────────────────────────────────────────────────────
+        CTBase.automatic_reference_documentation(;
+            subdirectory=".",
+            primary_modules=[CTModels => src("ocp/times.jl")],
+            exclude=EXCLUDE_SYMBOLS,
+            public=false,
+            private=true,
+            title="Times",
+            title_in_menu="Times",
+            filename="times",
+        ),
+        # ───────────────────────────────────────────────────────────────────
+        # OCP: State, Control, Variable
+        # ───────────────────────────────────────────────────────────────────
+        CTBase.automatic_reference_documentation(;
+            subdirectory=".",
+            primary_modules=[
+                CTModels => src("ocp/state.jl", "ocp/control.jl", "ocp/variable.jl")
+            ],
+            exclude=EXCLUDE_SYMBOLS,
+            public=false,
+            private=true,
+            title="State, Control & Variable",
+            title_in_menu="State, Control & Variable",
+            filename="state_control_variable",
+        ),
+        # ───────────────────────────────────────────────────────────────────
+        # OCP: Dynamics & Objective
+        # ───────────────────────────────────────────────────────────────────
+        CTBase.automatic_reference_documentation(;
+            subdirectory=".",
+            primary_modules=[CTModels => src("ocp/dynamics.jl", "ocp/objective.jl")],
+            exclude=EXCLUDE_SYMBOLS,
+            public=false,
+            private=true,
+            title="Dynamics & Objective",
+            title_in_menu="Dynamics & Objective",
+            filename="dynamics_objective",
+        ),
+        # ───────────────────────────────────────────────────────────────────
+        # OCP: Constraints
+        # ───────────────────────────────────────────────────────────────────
+        CTBase.automatic_reference_documentation(;
+            subdirectory=".",
+            primary_modules=[CTModels => src("ocp/constraints.jl")],
+            exclude=EXCLUDE_SYMBOLS,
+            public=false,
+            private=true,
+            title="Constraints",
+            title_in_menu="Constraints",
+            filename="constraints",
+        ),
+        # ───────────────────────────────────────────────────────────────────
+        # OCP: Solution & Dual
+        # ───────────────────────────────────────────────────────────────────
+        CTBase.automatic_reference_documentation(;
+            subdirectory=".",
+            primary_modules=[CTModels => src("ocp/solution.jl", "ocp/dual_model.jl")],
+            exclude=EXCLUDE_SYMBOLS,
+            public=false,
+            private=true,
+            title="Solution & Dual",
+            title_in_menu="Solution & Dual",
+            filename="solution_dual",
+        ),
+        # ───────────────────────────────────────────────────────────────────
+        # OCP: Print
+        # ───────────────────────────────────────────────────────────────────
+        CTBase.automatic_reference_documentation(;
+            subdirectory=".",
+            primary_modules=[CTModels => src("ocp/print.jl")],
+            exclude=EXCLUDE_SYMBOLS,
+            public=false,
+            private=true,
+            title="Print",
+            title_in_menu="Print",
+            filename="print",
+        ),
+        # ───────────────────────────────────────────────────────────────────
+        # Initial Guess
+        # ───────────────────────────────────────────────────────────────────
+        CTBase.automatic_reference_documentation(;
+            subdirectory=".",
+            primary_modules=[CTModels => src("init/initial_guess.jl")],
+            exclude=EXCLUDE_SYMBOLS,
+            public=false,
+            private=true,
+            title="Initial Guess",
+            title_in_menu="Initial Guess",
+            filename="initial_guess",
+        ),
+        # ───────────────────────────────────────────────────────────────────
+        # NLP Backends
+        # ───────────────────────────────────────────────────────────────────
+        CTBase.automatic_reference_documentation(;
+            subdirectory=".",
+            primary_modules=[
+                CTModels => src(
+                    "nlp/nlp_backends.jl",
+                    "nlp/options_schema.jl",
+                    "nlp/problem_core.jl",
+                    "nlp/discretized_ocp.jl",
+                    "nlp/model_api.jl",
+                ),
+            ],
+            exclude=EXCLUDE_SYMBOLS,
+            public=false,
+            private=true,
+            title="NLP Backends",
+            title_in_menu="NLP Backends",
+            filename="nlp",
+        ),
+    ]
+
+    # ───────────────────────────────────────────────────────────────────
+    # Extension: Plot
+    # ───────────────────────────────────────────────────────────────────
+    CTModelsPlots = Base.get_extension(CTModels, :CTModelsPlots)
+    if !isnothing(CTModelsPlots)
+        push!(
+            pages,
+            CTBase.automatic_reference_documentation(;
+                subdirectory=".",
+                primary_modules=[
+                    CTModelsPlots => ext(
+                        "CTModelsPlots.jl",
+                        "plot.jl",
+                        "plot_default.jl",
+                        "plot_utils.jl",
+                    ),
+                ],
+                external_modules_to_document=[Plots],
+                exclude=EXCLUDE_SYMBOLS,
+                public=false,
+                private=true,
+                title="Plot Extension",
+                title_in_menu="Plot",
+                filename="plot",
+            ),
+        )
+    end
+
+    # ───────────────────────────────────────────────────────────────────
+    # Extension: JLD & JSON (combined)
+    # ───────────────────────────────────────────────────────────────────
+    CTModelsJSON = Base.get_extension(CTModels, :CTModelsJSON)
+    CTModelsJLD = Base.get_extension(CTModels, :CTModelsJLD)
+    if !isnothing(CTModelsJSON) && !isnothing(CTModelsJLD)
+        push!(
+            pages,
+            CTBase.automatic_reference_documentation(;
+                subdirectory=".",
+                primary_modules=[
+                    CTModelsJSON => ext("CTModelsJSON.jl"),
+                    CTModelsJLD => ext("CTModelsJLD.jl"),
+                ],
+                external_modules_to_document=[CTModels],
+                exclude=EXCLUDE_SYMBOLS,
+                public=false,
+                private=true,
+                title="JLD & JSON Extension",
+                title_in_menu="JLD & JSON",
+                filename="import_export",
+            ),
+        )
+    end
+
+    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"))
+
+        for p in pages
+            filename = last(p)
+            fname = endswith(filename, ".md") ? filename : filename * ".md"
+            full_path = joinpath(docs_src, fname)
+
+            if isfile(full_path)
+                rm(full_path)
+                println("Removed temporary API doc: $full_path")
+            end
+        end
+    end
+end