Merge pull request #3713 from AayushSabharwal/as/docs

docs: make docs build

Author: ChrisRackauckas

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"

docs/make.jl

@@ -1,5 +1,9 @@
 using Documenter, ModelingToolkit
 using ModelingToolkit: SciMLBase
+# To load docstring from extension
+import FMI, CommonSolve, JumpProcesses
+
+MTKFMIExt = Base.get_extension(ModelingToolkit, :MTKFMIExt)
 
 # Make sure that plots don't throw a bunch of warnings / errors!
 ENV["GKSwstype"] = "100"
@@ -22,7 +26,7 @@ mathengine = MathJax3(Dict(:loader => Dict("load" => ["[tex]/require", "[tex]/ma
 
 makedocs(sitename = "ModelingToolkit.jl",
     authors = "Chris Rackauckas",
-    modules = [ModelingToolkit],
+    modules = [ModelingToolkit, MTKFMIExt],
     clean = true, doctest = false, linkcheck = true,
     warnonly = [:docs_block, :missing_docs, :cross_references],
     linkcheck_ignore = [
@@ -35,7 +39,9 @@ makedocs(sitename = "ModelingToolkit.jl",
         assets = ["assets/favicon.ico"],
         mathengine,
         canonical = "https://docs.sciml.ai/ModelingToolkit/stable/",
-        prettyurls = (get(ENV, "CI", nothing) == "true")),
+        prettyurls = (get(ENV, "CI", nothing) == "true"),
+        # This page gets especially big with all the problem docstrings
+        size_threshold_ignore = ["API/problems.md"]),
     pages = pages)
 
 deploydocs(repo = "github.com/SciML/ModelingToolkit.jl.git";

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

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
+```

docs/src/API/dynamic_opt.md

@@ -28,7 +28,7 @@ JuMPCollocation
 InfiniteOptCollocation
 CasADiCollocation
 PyomoCollocation
-solve(::AbstractDynamicOptProblem)
+CommonSolve.solve(::AbstractDynamicOptProblem)
 ```
 
 ### Problem constructors

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
 ```
 

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

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