docs: fix doc pages

AayushSabharwal · AayushSabharwal · commit c82be20866f2 · 2025-06-09T15:14:13.000+05:30
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -3,6 +3,7 @@ Attractors = "f3fd9213-ca85-4dba-9dfd-7fc91308fec7"
 BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
 BifurcationKit = "0f109fa4-8a5d-4b75-95aa-f515264e7665"
 CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
+CommonSolve = "38540f10-b2f7-11e9-35d8-d573e4eb0ff2"
 ControlSystemsBase = "aaaaaaaa-a6ca-5380-bf3e-84a91bcd477e"
 DataInterpolations = "82cc6244-b520-54b8-b5a6-8a565e85f1d0"
 DiffEqDevTools = "f3b72e0c-5b89-59e1-b016-84e28bfd966d"
@@ -13,6 +14,7 @@ FMI = "14a09403-18e3-468f-ad8a-74f8dda2d9ac"
 FMIZoo = "724179cf-c260-40a9-bd27-cccc6fe2f195"
 InfiniteOpt = "20393b10-9daf-11e9-18c9-8db751c92c57"
 Ipopt = "b6b21f68-93f8-5de0-b562-5493be1d77c9"
+JumpProcesses = "ccbc3e58-028d-4f4c-8cd5-9ae44345cda5"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 ModelingToolkit = "961ee093-0014-501f-94e3-6117800e7a78"
 ModelingToolkitStandardLibrary = "16a59e39-deab-5bd0-87e4-056b12336739"
diff --git a/docs/make.jl b/docs/make.jl
@@ -1,5 +1,7 @@
 using Documenter, ModelingToolkit
 using ModelingToolkit: SciMLBase
+# To load docstring from extension
+import FMI, CommonSolve, JumpProcesses
 
 # Make sure that plots don't throw a bunch of warnings / errors!
 ENV["GKSwstype"] = "100"
diff --git a/docs/src/API/System.md b/docs/src/API/System.md
@@ -32,7 +32,7 @@ or analysis points of the hierarchical system.
 ModelingToolkit.has_eqs
 ModelingToolkit.get_eqs
 equations
-equations_toplevel
+ModelingToolkit.equations_toplevel
 full_equations
 ModelingToolkit.has_noise_eqs
 ModelingToolkit.get_noise_eqs
@@ -44,17 +44,17 @@ ModelingToolkit.get_constraints
 constraints
 ModelingToolkit.has_costs
 ModelingToolkit.get_costs
-costs
+cost
 ModelingToolkit.has_consolidate
 ModelingToolkit.get_consolidate
 ModelingToolkit.has_unknowns
 ModelingToolkit.get_unknowns
 unknowns
-unknowns_toplevel
+ModelingToolkit.unknowns_toplevel
 ModelingToolkit.has_ps
 ModelingToolkit.get_ps
 parameters
-parameters_toplevel
+ModelingToolkit.parameters_toplevel
 tunable_parameters
 ModelingToolkit.has_brownians
 ModelingToolkit.get_brownians
@@ -77,19 +77,20 @@ defaults
 ModelingToolkit.has_guesses
 ModelingToolkit.get_guesses
 guesses
+ModelingToolkit.get_systems
 ModelingToolkit.has_initialization_eqs
 ModelingToolkit.get_initialization_eqs
 initialization_equations
 ModelingToolkit.has_continuous_events
 ModelingToolkit.get_continuous_events
 continuous_events
-continuous_events_toplevel
+ModelingToolkit.continuous_events_toplevel
 ModelingToolkit.has_discrete_events
 ModelingToolkit.get_discrete_events
-discrete_events_toplevel
+ModelingToolkit.discrete_events_toplevel
 ModelingToolkit.has_assertions
 ModelingToolkit.get_assertions
-assertions
+ModelingToolkit.assertions
 ModelingToolkit.has_metadata
 ModelingToolkit.get_metadata
 SymbolicUtils.getmetadata(::ModelingToolkit.AbstractSystem, ::DataType, ::Any)
@@ -144,8 +145,8 @@ has_diff_equations
 has_alg_equations
 diff_equations
 alg_equations
-is_alg_equation
-is_diff_equation
+ModelingToolkit.is_alg_equation
+ModelingToolkit.is_diff_equation
 ```
 
 ## String parsing
@@ -167,6 +168,18 @@ ModelingToolkit.dump_parameters
 ModelingToolkit.dump_variable_metadata
 ```
 
+## Inputs and outputs
+
+```@docs
+ModelingToolkit.inputs
+ModelingToolkit.outputs
+ModelingToolkit.bound_inputs
+ModelingToolkit.unbound_inputs
+ModelingToolkit.bound_outputs
+ModelingToolkit.unbound_outputs
+ModelingToolkit.is_bound
+```
+
 ## Debugging utilities
 
 ```@docs
diff --git a/docs/src/API/codegen.md b/docs/src/API/codegen.md
@@ -8,7 +8,6 @@ ModelingToolkit.generate_rhs
 ModelingToolkit.generate_diffusion_function
 ModelingToolkit.generate_jacobian
 ModelingToolkit.generate_tgrad
-ModelingToolkit.generate_hessian
 ModelingToolkit.generate_W
 ModelingToolkit.generate_dae_jacobian
 ModelingToolkit.generate_history
@@ -21,6 +20,7 @@ ModelingToolkit.generate_constraint_jacobian
 ModelingToolkit.generate_constraint_hessian
 ModelingToolkit.generate_control_jacobian
 ModelingToolkit.build_explicit_observed_function
+ModelingToolkit.generate_control_function
 ```
 
 For functions such as jacobian calculation which require symbolic computation, there
@@ -43,3 +43,9 @@ ModelingToolkit.calculate_constraint_jacobian
 ModelingToolkit.calculate_constraint_hessian
 ModelingToolkit.calculate_control_jacobian
 ```
+
+All code generation eventually calls `build_function_wrapper`.
+
+```@docs
+build_function_wrapper
+```
diff --git a/docs/src/API/dynamic_opt.md b/docs/src/API/dynamic_opt.md
@@ -28,7 +28,7 @@ JuMPCollocation
 InfiniteOptCollocation
 CasADiCollocation
 PyomoCollocation
-solve(::AbstractDynamicOptProblem)
+CommonSolve.solve(::AbstractDynamicOptProblem)
 ```
 
 ### Problem constructors
diff --git a/docs/src/API/model_building.md b/docs/src/API/model_building.md
@@ -81,7 +81,7 @@ Similar to the `stream` and `flow` keyword arguments in the specification, Model
 allows specifying how variables in a connector behave in a connection.
 
 ```@docs
-Equality
+ModelingToolkit.Equality
 Flow
 Stream
 ```
@@ -168,7 +168,6 @@ Symbolic affects are handled using equations as described in the [Events](@ref e
 section of the documentation. User-defined functions can be used via `ImperativeAffect`.
 
 ```@docs
-ModelingToolkit.AffectSystem
 ModelingToolkit.ImperativeAffect
 ```
 
diff --git a/docs/src/API/problems.md b/docs/src/API/problems.md
@@ -9,46 +9,46 @@ code for a variety of such numerical problems.
 ## Dynamical systems
 
 ```@docs
-ODEFunction(::System, args...)
-ODEProblem(::System, args...)
-DAEFunction(::System, args...)
-DAEProblem(::System, args...)
-SDEFunction(::System, args...)
-SDEProblem(::System, args...)
-DDEFunction(::System, args...)
-DDEProblem(::System, args...)
-SDDEFunction(::System, args...)
-SDDEProblem(::System, args...)
-JumpProblem(::System, args...)
-BVProblem(::System, args...)
-DiscreteProblem(::System, args...)
-ImplicitDiscreteProblem(::System, args...)
+SciMLBase.ODEFunction
+SciMLBase.ODEProblem
+SciMLBase.DAEFunction
+SciMLBase.DAEProblem
+SciMLBase.SDEFunction
+SciMLBase.SDEProblem
+SciMLBase.DDEFunction
+SciMLBase.DDEProblem
+SciMLBase.SDDEFunction
+SciMLBase.SDDEProblem
+JumpProcesses.JumpProblem
+SciMLBase.BVProblem
+SciMLBase.DiscreteProblem
+SciMLBase.ImplicitDiscreteProblem
 ```
 
 ## Nonlinear systems
 
 ```@docs
-NonlinearFunction(::System, args...)
-NonlinearProblem(::System, args...)
-SCCNonlinearProblem(::System, args...)
-NonlinearLeastSquaresProblem(::System, args...)
-SteadyStateProblem(::System, args...)
-IntervalNonlinearFunction(::System, args...)
-IntervalNonlinearProblem(::System, args...)
+SciMLBase.NonlinearFunction
+SciMLBase.NonlinearProblem
+SciMLBase.SCCNonlinearProblem
+SciMLBase.NonlinearLeastSquaresProblem
+SciMLBase.SteadyStateProblem
+SciMLBase.IntervalNonlinearFunction
+SciMLBase.IntervalNonlinearProblem
 ModelingToolkit.HomotopyContinuationProblem
-HomotopyNonlinearFunction(::System, args...)
+SciMLBase.HomotopyNonlinearFunction
 ```
 
 ## Optimization and optimal control
 
 ```@docs
-OptimizationFunction(::System, args...)
-OptimizationProblem(::System, args...)
-ODEInputFunction(::System, args...)
-JuMPDynamicOptProblem(::System, args...)
-InfiniteOptDynamicOptProblem,(::System, args...)
-CasADiDynamicOptProblem(::System, args...)
-DynamicOptSolution
+SciMLBase.OptimizationFunction
+SciMLBase.OptimizationProblem
+SciMLBase.ODEInputFunction
+ModelingToolkit.JuMPDynamicOptProblem
+ModelingToolkit.InfiniteOptDynamicOptProblem
+ModelingToolkit.CasADiDynamicOptProblem
+ModelingToolkit.DynamicOptSolution
 ```
 
 ## The state vector and parameter object
@@ -102,7 +102,7 @@ There are also utilities for manipulating the results of these analyses in a sym
 
 ```@docs
 ModelingToolkit.similarity_transform
-ModelingToolkit.reorder_unknnowns
+ModelingToolkit.reorder_unknowns
 ```
 
 ### Analysis point transformations
diff --git a/docs/src/API/variables.md b/docs/src/API/variables.md
@@ -1,4 +1,4 @@
-# Symbolic variables and variable metadata
+# [Symbolic variables and variable metadata](@id symbolic_metadata)
 
 ModelingToolkit uses [Symbolics.jl](https://docs.sciml.ai/Symbolics/stable/) for the symbolic
 manipulation infrastructure. In fact, the `@variables` macro is defined in Symbolics.jl. In
@@ -85,7 +85,7 @@ hasconnect
 getconnect
 ```
 
-```@docs; canonical = false
+```@docs; canonical=false
 Flow
 Stream
 ```
@@ -165,7 +165,7 @@ getguess
 When a system is constructed, the guesses of the involved variables are stored in a `Dict`
 in the system. After this point, the guess metadata of the variable is irrelevant.
 
-```@docs; canonical = false
+```@docs; canonical=false
 guesses
 ```
 
@@ -315,7 +315,7 @@ b = getbounds(sys) # Operating on the system, we get a dict
 
 See also:
 
-```@docs; canonical = false
+```@docs; canonical=false
 tunable_parameters
 ModelingToolkit.dump_unknowns
 ModelingToolkit.dump_parameters
diff --git a/docs/src/basics/Debugging.md b/docs/src/basics/Debugging.md
@@ -68,6 +68,6 @@ dprob[ModelingToolkit.ASSERTION_LOG_VARIABLE] = false;
 solve(dprob, Tsit5());
 ```
 
-```@docs
+```@docs; canonical = false
 debug_system
 ```
diff --git a/docs/src/basics/Events.md b/docs/src/basics/Events.md
@@ -249,11 +249,11 @@ par = @parameters g = 9.8
 bb_eqs = [D(x) ~ v
           D(v) ~ -g]
 
-function bb_affect!(integ, u, p, ctx)
-    integ.u[u.v] = -integ.u[u.v]
+function bb_affect!(mod, obs, integ, ctx)
+    return (; v = -mod.v)
 end
 
-reflect = [x ~ 0] => (bb_affect!, [v], [], [], nothing)
+reflect = [x ~ 0] => (bb_affect!, (; v))
 
 @mtkcompile bb_sys = System(bb_eqs, t, sts, par,
     continuous_events = reflect)
diff --git a/docs/src/basics/FAQ.md b/docs/src/basics/FAQ.md
@@ -88,7 +88,7 @@ Strings are not considered symbolic variables, and thus cannot directly be used
 indexing. However, ModelingToolkit does provide a method to parse the string representation of
 a variable, given the system in which that variable exists.
 
-```@docs
+```@docs; canonical = false
 ModelingToolkit.parse_variable
 ```
 
@@ -260,14 +260,14 @@ D = Differential(x)
 Tunable parameters are floating point parameters, not used in callbacks and not marked with `tunable = false` in their metadata. These are expected to be used with AD
 and optimization libraries. As such, they are stored together in one `Vector{T}`. To obtain the ordering of tunable parameters in this buffer, use:
 
-```@docs
+```@docs; canonical = false
 tunable_parameters
 ```
 
 If you have an array in which a particular dimension is in the order of tunable parameters (e.g. the jacobian with respect to tunables) then that dimension of the
 array can be reordered into the required permutation using the symbolic variables:
 
-```@docs
+```@docs; canonical = false
 reorder_dimension_by_tunables!
 reorder_dimension_by_tunables
 ```
diff --git a/docs/src/basics/InputOutput.md b/docs/src/basics/InputOutput.md
@@ -75,7 +75,7 @@ u = [rand()]
 
 ## Generating an output function, ``g``
 
-ModelingToolkit can also generate a function that computes a specified output of a system, the function ``y = g(x, u, p, t)`` above. This is done using the function [`build_explicit_observed_function`](@ref). When generating an output function, the user must specify the output variable(s) of interest, as well as any inputs if inputs are relevant to compute the output.
+ModelingToolkit can also generate a function that computes a specified output of a system, the function ``y = g(x, u, p, t)`` above. This is done using the function [`ModelingToolkit.build_explicit_observed_function`](@ref). When generating an output function, the user must specify the output variable(s) of interest, as well as any inputs if inputs are relevant to compute the output.
 
 The order of the user-specified output variables determines the order of the output vector ``y``.
 
@@ -93,7 +93,7 @@ See [Linearization](@ref linearization).
 Pages = ["InputOutput.md"]
 ```
 
-```@docs
+```@docs; canonical=false
 ModelingToolkit.generate_control_function
 ModelingToolkit.build_explicit_observed_function
 ```
diff --git a/docs/src/basics/Linearization.md b/docs/src/basics/Linearization.md
@@ -153,7 +153,7 @@ Also see [ControlSystemsMTK.jl](https://juliacontrol.github.io/ControlSystemsMTK
 Pages = ["Linearization.md"]
 ```
 
-```@docs
+```@docs; canonical = false
 linearize
 ModelingToolkit.linearize_symbolic
 ModelingToolkit.linearization_function
diff --git a/docs/src/internals.md b/docs/src/internals.md
@@ -3,44 +3,3 @@
 This is a page for detailing some of the inner workings to help future
 contributors to the library.
 
-## Observables and Variable Elimination
-
-In the variable “elimination” algorithms, what is actually done is that variables
-are removed from being unknowns and equations are moved into the `observed` category
-of the system. The `observed` equations are explicit algebraic equations which
-are then substituted out to completely eliminate these variables from the other
-equations, allowing the system to act as though these variables no longer exist.
-
-However, a user may want to interact with such variables, for example,
-plotting their output. For this reason, these relationships are stored,
-and are then used to generate the `observed` equation found in the
-`SciMLFunction` interface, so that `sol[x]` lazily reconstructs the observed
-variable when necessary. In this sense, there is an equivalence between
-observables and the variable elimination system.
-
-The procedure for variable elimination inside [`mtkcompile`](@ref) is
-
- 1. [`ModelingToolkit.initialize_system_structure`](@ref).
- 2. [`ModelingToolkit.alias_elimination`](@ref). This step moves equations into `observed(sys)`.
- 3. [`ModelingToolkit.dae_index_lowering`](@ref) by means of [`pantelides!`](@ref) (if the system is an [`System`](@ref)).
- 4. [`ModelingToolkit.tearing`](@ref).
-
-## Preparing a system for simulation
-
-Before a simulation or optimization can be performed, the symbolic equations stored in an [`AbstractSystem`](@ref) must be converted into executable code. This step typically occurs after the simplification explained above, and is performed when an instance of a [`SciMLBase.AbstractSciMLProblem`](@ref), such as a [`ODEProblem`](@ref), is constructed.
-The call chain typically looks like this, with the function names in the case of an `System` indicated in parentheses
-
- 1. Problem constructor ([`ODEProblem`](@ref))
- 2. Build an `DEFunction` ([`process_DEProblem`](@ref) -> [`ODEFunction`](@ref)
- 3. Write actual executable code ([`generate_function`](@ref) or [`generate_custom_function`](@ref))
-
-Apart from [`generate_function`](@ref), which generates the dynamics function, `ODEFunction` also builds functions for observed equations (`build_explicit_observed_function`) and Jacobians (`generate_jacobian`) etc. These are all stored in the `ODEFunction`.
-
-## Creating an `MTKParameters` object
-
-It may be useful to create a parameter object without creating the problem. For this
-purpose, the `MTKParameters` constructor is exposed as public API.
-
-```@docs
-MTKParameters
-```
diff --git a/docs/src/tutorials/SampledData.md b/docs/src/tutorials/SampledData.md
diff --git a/docs/src/tutorials/disturbance_modeling.md b/docs/src/tutorials/disturbance_modeling.md
diff --git a/docs/src/tutorials/initialization.md b/docs/src/tutorials/initialization.md
diff --git a/docs/src/tutorials/linear_analysis.md b/docs/src/tutorials/linear_analysis.md
diff --git a/docs/src/tutorials/stochastic_diffeq.md b/docs/src/tutorials/stochastic_diffeq.md
