Merge pull request #842 from SciML/doc_home_update

[Non-urgent - Ready] Doc home update

docs/src/api.md

@@ -1,4 +1,4 @@
-# Catalyst.jl API
+# [Catalyst.jl API](@id api)
 ```@meta
 CurrentModule = Catalyst
 ```

docs/src/introduction_to_catalyst/introduction_to_catalyst.md

@@ -44,7 +44,7 @@ listed chemical species and unknowns. [`@reaction_network`](@ref) returns a
 [`ReactionSystem`](@ref), which we saved in the `repressilator` variable. It can
 be converted to a variety of other mathematical models represented as
 `ModelingToolkit.AbstractSystem`s, or analyzed in various ways using the
-[Catalyst.jl API](@ref). For example, to see the chemical species, parameters,
+[Catalyst.jl API](@ref api). For example, to see the chemical species, parameters,
 and reactions we can use
 ```@example tut1
 species(repressilator)

docs/src/inverse_problems/global_sensitivity_analysis.md

@@ -142,7 +142,7 @@ Here, the function's sensitivity is evaluated with respect to each output indepe
 
 ---
 ## [Citations](@id global_sensitivity_analysis_citations)
-If you use this functionality in your research, [in addition to Catalyst](@ref catalyst_citation), please cite the following paper to support the authors of the GlobalSensitivity.jl package:
+If you use this functionality in your research, [in addition to Catalyst](@ref doc_index_citation), please cite the following paper to support the authors of the GlobalSensitivity.jl package:
 ```
 @article{dixit2022globalsensitivity,
   title={GlobalSensitivity. jl: Performant and Parallel Global Sensitivity Analysis with Julia},

docs/src/model_creation/model_file_loading_and_export.md

@@ -1,7 +1,7 @@
-# Loading Chemical Reaction Network Models from Files
+# [Loading Chemical Reaction Network Models from Files](@id model_file_import_export)
 Catalyst stores chemical reaction network (CRN) models in `ReactionSystem` structures. This tutorial describes how to load such `ReactionSystem`s from, and save them to, files. This can be used to save models between Julia sessions, or transfer them from one session to another. Furthermore, to facilitate the computation modelling of CRNs, several standardised file formats have been created to represent CRN models (e.g. [SBML](https://sbml.org/)). This enables CRN models to be shared between different softwares and programming languages. While Catalyst itself does not have the functionality for loading such files, we will here (briefly) introduce a few packages that can load different file types to Catalyst `ReactionSystem`s.
 
-## Saving Catalyst models to, and loading them from, Julia files
+## [Saving Catalyst models to, and loading them from, Julia files](@id model_file_import_export_crn_serialization)
 Catalyst provides a `save_reactionsystem` function, enabling the user to save a `ReactionSystem` to a file. Here we demonstrate this by first creating a [simple cross-coupling model](@ref basic_CRN_library_cc):
 ```@example file_handling_1
 using Catalyst
@@ -56,7 +56,7 @@ end
 
 In addition to transferring models between Julia sessions, the `save_reactionsystem` function can also be used or print a model to a text file where you can easily inspect its components.
 
-## Loading and Saving arbitrary Julia variables using Serialization.jl
+## [Loading and Saving arbitrary Julia variables using Serialization.jl](@id model_file_import_export_julia_serialisation)
 Julia provides a general and lightweight interface for loading and saving Julia structures to and from files that it can be good to be aware of. It is called [Serialization.jl](https://docs.julialang.org/en/v1/stdlib/Serialization/) and provides two functions, `serialize` and `deserialize`. The first allows us to write a Julia structure to a file. E.g. if we wish to save a parameter set associated with our model, we can use
 ```@example file_handling_2
 using Serialization
@@ -70,7 +70,7 @@ rm("saved_parameters.jls") # hide
 loaded_sol # hide
 ```
 
-## [Loading .net files using ReactionNetworkImporters.jl](@id file_loading_rni_net)
+## [Loading .net files using ReactionNetworkImporters.jl](@id model_file_import_export_sbml_rni_net)
 A general-purpose format for storing CRN models is so-called .net files. These can be generated by e.g. [BioNetGen](https://bionetgen.org/). The [ReactionNetworkImporters.jl](https://github.com/SciML/ReactionNetworkImporters.jl) package enables the loading of such files to Catalyst `ReactionSystem`. Here we load a [Repressilator](@ref basic_CRN_library_repressilator) model stored in the "repressilator.net" file:
 ```julia
 using ReactionNetworkImporters
@@ -96,15 +96,15 @@ Note that, as all initial conditions and parameters have default values, we can
 
 A more detailed description of ReactionNetworkImporter's features can be found in its [documentation](https://docs.sciml.ai/ReactionNetworkImporters/stable/).
 
-## Loading SBML files using SBMLImporter.jl and SBMLToolkit.jl
+## [Loading SBML files using SBMLImporter.jl and SBMLToolkit.jl](@id model_file_import_export_sbml)
 The Systems Biology Markup Language (SBML) is the most widespread format for representing CRN models. Currently, there exist two different Julia packages, [SBMLImporter.jl](https://github.com/sebapersson/SBMLImporter.jl) and [SBMLToolkit.jl](https://github.com/SciML/SBMLToolkit.jl), that are able to load SBML files to Catalyst `ReactionSystem` structures. SBML is able to represent a *very* wide range of model features, with both packages supporting most features. However, there exist SBML files (typically containing obscure model features such as events with time delays) that currently cannot be loaded into Catalyst models.
 
 SBMLImporter's `load_SBML` function can be used to load SBML files. Here, we load a [Brusselator](@ref basic_CRN_library_brusselator) model stored in the "brusselator.xml" file:
 ```julia
 using SBMLImporter
 prn, cbs = load_SBML("brusselator.xml", massaction = true)
 ```
-Here, while [ReactionNetworkImporters generates a `ParsedReactionSystem` only](@ref file_loading_rni_net), SBMLImporter generates a `ParsedReactionSystem` (here stored in `prn`) and a [so-called `CallbackSet`](https://docs.sciml.ai/DiffEqDocs/stable/features/callback_functions/#CallbackSet) (here stored in `cbs`). While `prn` can be used to create various problems, when we simulate them, we must also supply `cbs`. E.g. to simulate our brusselator we use:
+Here, while [ReactionNetworkImporters generates a `ParsedReactionSystem` only](@ref model_file_import_export_sbml_rni_net), SBMLImporter generates a `ParsedReactionSystem` (here stored in `prn`) and a [so-called `CallbackSet`](https://docs.sciml.ai/DiffEqDocs/stable/features/callback_functions/#CallbackSet) (here stored in `cbs`). While `prn` can be used to create various problems, when we simulate them, we must also supply `cbs`. E.g. to simulate our brusselator we use:
 ```julia
 using Catalyst, OrdinaryDiffEq, Plots
 tspan = (0.0, 50.0)
@@ -121,10 +121,10 @@ A more detailed description of SBMLImporter's features can be found in its [docu
 !!! note
     The `massaction = true` option informs the importer that the target model follows mass-action principles. When given, this enables SBMLImporter to make appropriate modifications to the model (which are important for e.g. jump simulation performance).
 
-### SBMLImporter and SBMLToolkit
+### [SBMLImporter and SBMLToolkit](@id model_file_import_export_package_alts)
 Above, we described how to use SBMLImporter to import SBML files. Alternatively, SBMLToolkit can be used instead. It has a slightly different syntax, which is described in its [documentation](https://github.com/SciML/SBMLToolkit.jl), and does not support as wide a range of SBML features as SBMLImporter. A short comparison of the two packages can be found [here](https://github.com/sebapersson/SBMLImporter.jl?tab=readme-ov-file#differences-compared-to-sbmltoolkit). Generally, while they both perform well, we note that for *jump simulations* SBMLImporter is preferable (its way for internally representing reaction event enables more performant jump simulations).
 
-## Loading models from matrix representation using ReactionNetworkImporters.jl
+## [Loading models from matrix representation using ReactionNetworkImporters.jl](@id model_file_import_export_matrix_representations)
 While CRN models can be represented through various file formats, they can also be represented in various matrix forms. E.g. a CRN with $m$ species and $n$ reactions (and with constant rates) can be represented with either
 - An $mxn$ substrate matrix (with each species's substrate stoichiometry in each reaction) and an $nxm$ product matrix (with each species's product stoichiometry in each reaction).
 
@@ -136,7 +136,7 @@ The advantage of these forms is that they offer a compact and very general way t
 
 ---
 ## [Citations](@id petab_citations)
-If you use any of this functionality in your research, [in addition to Catalyst](@ref catalyst_citation), please cite the paper(s) corresponding to whichever package(s) you used:
+If you use any of this functionality in your research, [in addition to Catalyst](@ref doc_index_citation), please cite the paper(s) corresponding to whichever package(s) you used:
 ```
 @software{2022ReactionNetworkImporters,
   author       = {Isaacson, Samuel},

docs/src/model_creation/programmatic_CRN_construction.md

@@ -180,7 +180,7 @@ This ensured they were properly treated as species and not parameters. See the
 
 ## Basic querying of `ReactionSystems`
 
-The [Catalyst.jl API](@ref) provides a large variety of functionality for
+The [Catalyst.jl API](@ref api) provides a large variety of functionality for
 querying properties of a reaction network. Here we go over a few of the most
 useful basic functions. Given the `repressillator` defined above we have that
 ```@example ex
@@ -247,5 +247,5 @@ rx1.prodstoich
 rx1.netstoich
 ```
 
-See the [Catalyst.jl API](@ref) for much more detail on the various querying and
+See the [Catalyst.jl API](@ref api) for much more detail on the various querying and
 analysis functions provided by Catalyst.

docs/src/steady_state_functionality/dynamical_systems.md

@@ -124,7 +124,7 @@ More details on how to compute Lyapunov exponents using DynamicalSystems.jl can
 
 ---
 ## [Citations](@id dynamical_systems_citations)
-If you use this functionality in your research, [in addition to Catalyst](@ref catalyst_citation), please cite the following paper to support the author of the DynamicalSystems.jl package:
+If you use this functionality in your research, [in addition to Catalyst](@ref doc_index_citation), please cite the following paper to support the author of the DynamicalSystems.jl package:
 ```
 @article{DynamicalSystems.jl-2018,
   doi = {10.21105/joss.00598},

docs/src/steady_state_functionality/nonlinear_solve.md

@@ -133,7 +133,7 @@ However, especially when the forward ODE simulation approach is used, it is reco
 
 ---
 ## [Citations](@id nonlinear_solve_citation)
-If you use this functionality in your research, [in addition to Catalyst](@ref catalyst_citation), please cite the following paper to support the authors of the NonlinearSolve.jl package:
+If you use this functionality in your research, [in addition to Catalyst](@ref doc_index_citation), please cite the following paper to support the authors of the NonlinearSolve.jl package:
 ```
 @article{pal2024nonlinearsolve,
   title={NonlinearSolve. jl: High-Performance and Robust Solvers for Systems of Nonlinear Equations in Julia},

docs/src/steady_state_functionality/steady_state_stability_computation.md

@@ -1,10 +1,10 @@
-# Steady state stability computation
+# [Steady state stability computation](@id steady_state_stability)
 After system steady states have been found using [HomotopyContinuation.jl](@ref homotopy_continuation), [NonlinearSolve.jl](@ref steady_state_solving), or other means, their stability can be computed using Catalyst's `steady_state_stability` function. Systems with conservation laws will automatically have these removed, permitting stability computation on systems with singular Jacobian.
 
 !!! warn 
     Catalyst currently computes steady state stabilities using the naive approach of checking whether a system's largest eigenvalue real part is negative. While more advanced stability computation methods exist (and would be a welcome addition to Catalyst), there is no direct plans to implement these. Furthermore, Catalyst uses a tolerance `tol = 10*sqrt(eps())` to determine whether a computed eigenvalue is far away enough from 0 to be reliably used. This threshold can be changed through the `tol` keyword argument.
 
-## Basic examples
+## [Basic examples](@id steady_state_stability_basics)
 Let us consider the following basic example:
 ```@example stability_1
 using Catalyst
@@ -42,7 +42,7 @@ Finally, as described above, Catalyst uses an optional argument, `tol`, to deter
 nothing# hide
 ```
 
-## Pre-computing the Jacobian to increase performance when computing stability for many steady states
+## [Pre-computing the Jacobian to increase performance when computing stability for many steady states](@id steady_state_stability_jacobian)
 Catalyst uses the system Jacobian to compute steady state stability, and the Jacobian is computed once for each call to `steady_state_stability`. If you repeatedly compute stability for steady states of the same system, pre-computing the Jacobian and supplying it to the `steady_state_stability` function can improve performance. 
 
 In this example we use the self-activation loop from previously, pre-computes its Jacobian, and uses it to multiple `steady_state_stability` calls:

docs/unpublished/petab_ode_param_fitting.md

@@ -523,7 +523,7 @@ There exist several types of plots for both types of calibration results. More d
 
 ---
 ## [Citations](@id petab_citations)
-If you use this functionality in your research, [in addition to Catalyst](@ref catalyst_citation), please cite the following papers to support the authors of the PEtab.jl package (currently there is no article associated with this package) and the PEtab standard:
+If you use this functionality in your research, [in addition to Catalyst](@ref doc_index_citation), please cite the following papers to support the authors of the PEtab.jl package (currently there is no article associated with this package) and the PEtab standard:
 ```
 @misc{2023Petabljl,
   author       = {Ognissanti, Damiano AND Arutjunjan, Rafael AND Persson, Sebastian AND Hasselgren, Viktor},