Document umbrella re-exported API (#3970)

Render the common solve, problem, callback, utility, AD, and module interfaces exported by OrdinaryDiffEq so public API documentation QA covers the umbrella package.

Co-authored-by: ChrisRackauckas-Claude <accounts@chrisrackauckas.com>

Author: ChrisRackauckas-Claude

docs/Project.toml

@@ -35,6 +35,8 @@ OrdinaryDiffEqStabilizedRK = "358294b1-0aab-51c3-aafe-ad5ab194a2ad"
 OrdinaryDiffEqSymplecticRK = "fa646aed-7ef9-47eb-84c4-9443fc8cbfa8"
 OrdinaryDiffEqTsit5 = "b1df2697-797e-41e3-8120-5422d3b24e4a"
 OrdinaryDiffEqVerner = "79d7bb75-1356-48c1-b8c0-6832512096c2"
+SciMLBase = "0bca4576-84f4-4d90-8ffe-ffa030f20462"
+SciMLLogging = "a6db7da4-7206-11f0-1eab-35f2a5dbe1d1"
 
 [sources]
 DiffEqBase = {path = "../lib/DiffEqBase"}
@@ -109,3 +111,5 @@ OrdinaryDiffEqStabilizedRK = "2.0.0"
 OrdinaryDiffEqSymplecticRK = "2.0.0"
 OrdinaryDiffEqTsit5 = "2.0.0"
 OrdinaryDiffEqVerner = "2.0.0"
+SciMLBase = "3.35.1"
+SciMLLogging = "2.0.0"

docs/make.jl

@@ -1,4 +1,5 @@
 using Documenter, OrdinaryDiffEq, DiffEqDevTools
+import SciMLBase, SciMLLogging
 using DiffEqBase
 using OrdinaryDiffEqCore
 # Bring controller API symbols into Main so unqualified @ref links in
@@ -8,6 +9,46 @@ using OrdinaryDiffEqCore: default_controller, resolve_basic,
     get_EEst, set_EEst!, CompositeController
 using OrdinaryDiffEqNonlinearSolve
 using ImplicitDiscreteSolve
+
+# Register the re-exported bindings with the umbrella module for Documenter.
+for (name, owner) in (
+        (:solve, "CommonSolve.solve"),
+        (:solve!, "CommonSolve.solve!"),
+        (:init, "CommonSolve.init"),
+        (:step!, "CommonSolve.step!"),
+        (:ODEProblem, "SciMLBase.ODEProblem"),
+        (:ODEFunction, "SciMLBase.ODEFunction"),
+        (:ODESolution, "SciMLBase.ODESolution"),
+        (:SplitODEProblem, "SciMLBase.SplitODEProblem"),
+        (:SplitFunction, "SciMLBase.SplitFunction"),
+        (:SecondOrderODEProblem, "SciMLBase.SecondOrderODEProblem"),
+        (:DynamicalODEProblem, "SciMLBase.DynamicalODEProblem"),
+        (:DAEProblem, "SciMLBase.DAEProblem"),
+        (:DAEFunction, "SciMLBase.DAEFunction"),
+        (:DAESolution, "SciMLBase.DAESolution"),
+        (:EnsembleProblem, "SciMLBase.EnsembleProblem"),
+        (:CallbackSet, "SciMLBase.CallbackSet"),
+        (:ContinuousCallback, "SciMLBase.ContinuousCallback"),
+        (:DiscreteCallback, "SciMLBase.DiscreteCallback"),
+        (:VectorContinuousCallback, "SciMLBase.VectorContinuousCallback"),
+        (:ODEAliasSpecifier, "SciMLBase.ODEAliasSpecifier"),
+        (:add_tstop!, "SciMLBase.add_tstop!"),
+        (:derivative_discontinuity!, "SciMLBase.derivative_discontinuity!"),
+        (:reinit!, "SciMLBase.reinit!"),
+        (:remake, "SciMLBase.remake"),
+        (:set_proposed_dt!, "SciMLBase.set_proposed_dt!"),
+        (:successful_retcode, "SciMLBase.successful_retcode"),
+        (:AutoFiniteDiff, "ADTypes.AutoFiniteDiff"),
+        (:AutoForwardDiff, "ADTypes.AutoForwardDiff"),
+        (:AutoSparse, "ADTypes.AutoSparse"),
+        (:DefaultODEAlgorithm, "OrdinaryDiffEqDefault.DefaultODEAlgorithm"),
+    )
+    doc = "Re-export of `$owner`."
+    Core.eval(OrdinaryDiffEq, :(@doc $doc $name))
+end
+
+@eval SciMLBase @doc "The common interfaces and types used throughout the SciML ecosystem." SciMLBase
+@eval SciMLLogging @doc "The common logging interface used by SciML solvers." SciMLLogging
 using OrdinaryDiffEqAMF
 using OrdinaryDiffEqAdamsBashforthMoulton
 using OrdinaryDiffEqBDF
@@ -50,6 +91,9 @@ makedocs(
     doctest = false,
     modules = [
         OrdinaryDiffEq,
+        SciMLBase,
+        SciMLBase.ReturnCode,
+        SciMLLogging,
         DiffEqBase,
         OrdinaryDiffEqCore,
         OrdinaryDiffEqNonlinearSolve,

docs/pages.jl

@@ -54,6 +54,7 @@ pages = [
         "misc.md",
     ],
     "APIs" => [
+        "api/common_interface.md",
         "api/diffeqbase.md",
         "api/ordinarydiffeqcore.md",
         "api/controllers.md",

docs/src/api/common_interface.md

@@ -0,0 +1,79 @@
+# Common Interface API
+
+OrdinaryDiffEq re-exports the common problem, callback, solve, and automatic
+differentiation interfaces needed to construct and solve ordinary differential
+equations.
+
+## Solve interface
+
+```@docs
+OrdinaryDiffEq.solve
+OrdinaryDiffEq.solve!
+OrdinaryDiffEq.init
+OrdinaryDiffEq.step!
+```
+
+## Problem types
+
+```@docs
+OrdinaryDiffEq.ODEProblem
+OrdinaryDiffEq.ODEFunction
+OrdinaryDiffEq.ODESolution
+OrdinaryDiffEq.SplitODEProblem
+OrdinaryDiffEq.SplitFunction
+OrdinaryDiffEq.SecondOrderODEProblem
+OrdinaryDiffEq.DynamicalODEProblem
+OrdinaryDiffEq.DAEProblem
+OrdinaryDiffEq.DAEFunction
+OrdinaryDiffEq.DAESolution
+OrdinaryDiffEq.EnsembleProblem
+```
+
+### Ensemble context
+
+```@docs; canonical=false
+SciMLBase.EnsembleContext
+```
+
+## Callbacks
+
+```@docs
+OrdinaryDiffEq.CallbackSet
+OrdinaryDiffEq.ContinuousCallback
+OrdinaryDiffEq.DiscreteCallback
+OrdinaryDiffEq.VectorContinuousCallback
+```
+
+## Solution and integrator utilities
+
+```@docs
+OrdinaryDiffEq.ReturnCode
+OrdinaryDiffEq.ODEAliasSpecifier
+OrdinaryDiffEq.add_tstop!
+OrdinaryDiffEq.derivative_discontinuity!
+OrdinaryDiffEq.reinit!
+OrdinaryDiffEq.remake
+OrdinaryDiffEq.set_proposed_dt!
+OrdinaryDiffEq.successful_retcode
+```
+
+## Automatic differentiation
+
+```@docs
+OrdinaryDiffEq.AutoFiniteDiff
+OrdinaryDiffEq.AutoForwardDiff
+OrdinaryDiffEq.AutoSparse
+```
+
+## Default algorithm
+
+```@docs
+OrdinaryDiffEq.DefaultODEAlgorithm
+```
+
+## Interface modules
+
+```@docs
+OrdinaryDiffEq.SciMLBase
+OrdinaryDiffEq.SciMLLogging
+```