WIP: beginning to refactor network analysis docs

docs/Project.toml

@@ -18,6 +18,7 @@ Latexify = "23fbe1c1-3f47-55db-b15f-69d7ec21a316"
 LinearSolve = "7ed4a6bd-45f5-4d41-b270-4a48e9bafcae"
 Logging = "56ddb016-857b-54e1-b83d-db4d58db5568"
 ModelingToolkit = "961ee093-0014-501f-94e3-6117800e7a78"
+MultiDocumenter = "87ed4bf0-c935-4a67-83c3-2a03bee4197c"
 NetworkLayout = "46757867-2c16-5918-afeb-47bfcb05e46a"
 NonlinearSolve = "8913a72c-1f9b-4ce2-8d82-65094dcecaec"
 Optim = "429524aa-4258-5aef-a3af-852621145aeb"

docs/make.jl

@@ -2,6 +2,7 @@ using Documenter
 using Catalyst, ModelingToolkit
 # Add packages for plotting
 using GraphMakie, CairoMakie
+using MultiDocumenter
 
 docpath = Base.source_dir()
 assetpath = joinpath(docpath, "src", "assets")
@@ -48,5 +49,32 @@ makedocs(sitename = "Catalyst.jl",
     pagesonly = true,
     warnonly = [:missing_docs])
 
+clonedir = mktempdir()
+
+docs = [MultiDocumenter.MultiDocRef(
+        upstream = joinpath(@__DIR__, "build"),
+        path = "docs",
+        name = "Catalyst",
+        fix_canonical_url = false,
+        ),
+        MultiDocumenter.MultiDocRef(
+        upstream = joinpath(clonedir, "build"),
+        path = "NetworkAnalysis",
+        name = "CatalystNetworkAnalysis",
+        giturl = "https://github.com/SciML/CatalystNetworkAnalysis.jl",
+        )]
+
 deploydocs(repo = "github.com/SciML/Catalyst.jl.git";
     push_preview = true)
+
+outpath = joinpath(@__DIR__, "build")
+MultiDocumenter.make(outpath, docs;
+                     assets_dir = "docs/src/assets",
+                     search_engine = MultiDocumenter.SearchConfig(index_versions = [
+                                                                      "stable",
+                                                                  ],
+                                                                  engine = MultiDocumenter.FlexSearch),
+                     brand_image = MultiDocumenter.BrandImage("https://sciml.ai",
+                                                              joinpath("assets",
+                                                                       "logo.png")))
+

docs/pages.jl

@@ -16,7 +16,6 @@ pages = Any[
         "model_creation/model_file_loading_and_export.md",
         "model_creation/model_visualisation.md",
         "model_creation/reactionsystem_content_accessing.md",
-        "model_creation/network_analysis.md",
         "model_creation/chemistry_related_functionality.md",
         "Examples" => Any[
             "model_creation/examples/basic_CRN_library.md",
@@ -25,6 +24,12 @@ pages = Any[
             "model_creation/examples/smoluchowski_coagulation_equation.md"
         ]
     ],
+    "Network Analysis" => Any[
+        "network_analysis/odes.md",
+        "network_analysis/crnt.md",
+        "network_analysis/network_properties.md",
+        "network_analysis/advanced_analysis.md"
+    ],
     "Model simulation and visualization" => Any[
         "model_simulation/simulation_introduction.md",
         "model_simulation/simulation_plotting.md",
@@ -62,6 +67,9 @@ pages = Any[
         "spatial_modelling/spatial_jump_simulations.md"
     ],
     "FAQs" => "faqs.md",
-    "API" => "api.md",
+    "API" => Any[
+                 "api/core_api.md",
+                 "api/network_analysis_api.md"
+                ],
     "Developer Documentation" => "devdocs/dev_guide.md"
 ]

docs/src/api.md → docs/src/api/core_api.md

@@ -238,32 +238,6 @@ ModelingToolkit.compose
 Catalyst.flatten
 ```
 
-## Network analysis and representations
-Note, currently API functions for network analysis and conservation law analysis
-do not work with constant species (currently only generated by SBMLToolkit).
-
-```@docs
-conservationlaws
-conservedquantities
-conservedequations
-conservationlaw_constants
-ReactionComplexElement
-ReactionComplex
-reactioncomplexmap
-reactioncomplexes
-incidencemat
-complexstoichmat
-complexoutgoingmat
-incidencematgraph
-linkageclasses
-deficiency
-subnetworks
-linkagedeficiencies
-isreversible
-isweaklyreversible
-reset_networkproperties!
-```
-
 ## Network comparison
 ```@docs
 ==(rn1::Reaction, rn2::Reaction)

docs/src/api/network_analysis_api.md

@@ -0,0 +1,41 @@
+# [Network analysis and representations](@id api_network_analysis)
+```@meta
+CurrentModule = Catalyst
+```
+
+Note, currently API functions for network analysis and conservation law analysis
+do not work with constant species (currently only generated by SBMLToolkit).
+
+For more information about these functions, please see the sections of the docs on
+[network ODE representation](@ref network_analysis_odes) and [chemical reaction network theory](@ref network_analysis_structural_aspects).
+
+```@docs
+conservationlaws
+conservedquantities
+conservedequations
+conservationlaw_constants
+ReactionComplexElement
+ReactionComplex
+reactioncomplexmap
+reactioncomplexes
+incidencemat
+incidencematgraph
+complexstoichmat
+complexoutgoingmat
+fluxmat
+adjacencymat
+laplacianmat
+massactionvector
+linkageclasses
+deficiency
+linkagedeficiencies
+satisfiesdeficiencyone
+satisfiesdeficiencyzero
+subnetworks
+isreversible
+isweaklyreversible
+iscomplexbalanced
+isdetailedbalanced
+robustspecies
+reset_networkproperties!
+```

docs/src/index.md

@@ -23,7 +23,7 @@ etc).
 - The [Catalyst.jl API](@ref api) provides functionality for building networks programmatically and for composing multiple networks together.
 - Leveraging ModelingToolkit, generated models can be converted to symbolic reaction rate equation ODE models, symbolic Chemical Langevin Equation models, and symbolic stochastic chemical kinetics (jump process) models. These can be simulated using any [DifferentialEquations.jl](https://docs.sciml.ai/DiffEqDocs/stable/) [ODE/SDE/jump solver](@ref simulation_intro), and can be used within `EnsembleProblem`s for carrying out [parallelized parameter sweeps and statistical sampling](@ref ensemble_simulations). Plot recipes are available for [visualization of all solutions](@ref simulation_plotting).
 - Non-integer (e.g. `Float64`) stoichiometric coefficients [are supported](@ref dsl_description_stoichiometries_decimal) for generating ODE models, and symbolic expressions for stoichiometric coefficients [are supported](@ref parametric_stoichiometry) for all system types.
-- A [network analysis suite](@ref network_analysis) permits the computation of linkage classes, deficiencies, reversibility, and other network properties.
+- A [network analysis suite](@ref network_analysis_structural_aspects) permits the computation of linkage classes, deficiencies, reversibility, and other network properties.
 - [Conservation laws can be detected and utilized](@ref conservation_laws) to reduce system sizes, and to generate non-singular Jacobians (e.g. during conversion to ODEs, SDEs, and steady state equations).
 - Catalyst reaction network models can be [coupled with differential and algebraic equations](@ref constraint_equations_coupling_constraints) (which are then incorporated during conversion to ODEs, SDEs, and steady state equations).
 - Models can be [coupled with events](@ref constraint_equations_events) that affect the system and its state during simulations.

docs/src/network_analysis/advanced_analysis.md

@@ -0,0 +1,4 @@
+# [Advanced Analysis using CatalystNetworkAnalysis](@id catalyst_network_analysis)
+
+For more advanced chemical reaction network analysis, there is a special CatalystNetworkAnalysis package. This package has functionality for a wider range of analysis for chemical reaction networks. For more information, please see the CatalystNetworkAnalysis section accessible from the header of this page.
+