Merge pull request #1197 from SciML/misc_doc_fixes

[WIP] Minor docfixes

Author: TorkelE

README.md

@@ -137,9 +137,9 @@ model. Here we instead show how various Catalyst features can compose to create
 a much more advanced model. Our model describes how the volume of a cell ($V$)
 is affected by a growth factor ($G$). The growth factor only promotes growth
 while in its phosphorylated form ($G^P$). The phosphorylation of $G$ ($G \to G^P$)
-is promoted by sunlight (modeled as the cyclic sinusoid $k_a (\sin(t) + 1)$),
-which phosphorylates the growth factor (producing $G^P$). When the cell reaches a
-critical volume ($V_m$) it undergoes cell division. First, we declare our model:
+is promoted by sunlight, which is modeled as the cyclic sinusoid $k_a (\sin(t) + 1)$. 
+When the cell reaches a critical volume ($V_m$) it undergoes cell division. First, we 
+declare our model:
 ```julia
 using Catalyst
 cell_model = @reaction_network begin

docs/src/devdocs/dev_guide.md

@@ -1,28 +1,23 @@
 # Catalyst Developer Documentation
 
-## Release Process
+## [Release Process](@id devdocs_releaseprocess)
 Beginning with v15, Catalyst is using a new release process to try to ensure
 continuing stability of releases. Before making a release one should
 
-1. Create a new release branch, i.e. "release-15.0.0"
+1. Create a new release branch, i.e. "release-15.0.0".
 2. On this branch, cap major dependencies to their latest version that works and
    for which tests pass.
    - Caps need to be included in both Project.toml and docs/Project.toml.
    - Do not cap the master branch as this can prevent upstream libraries from
      properly testing against Catalyst, and hide breaking changes that impact
      Catalyst.
-3. Check docs build with the capped dependencies. Visually verify via checking
-   the artifact in the doc build that the docs actually look ok (since sometimes
-   issues can arise that do not lead to actual errors in the doc CI).
-4. Release via the [registration
+3. [Check docs build](@ref devdocs_advice_doc_inspection) with the capped dependencies. 
+   Visually verify via checking the artifact in the doc build that the docs actually
+   look ok (since sometimes issues can arise that do not lead to actual errors in the doc CI).
+5. Release via the [registration
    issue](https://github.com/SciML/Catalyst.jl/issues/127) with the
-   command:
-   
-    ```
-    @JuliaRegistrator register branch=release-15.0.0
-    ```
-    
-    modifying as appropriate for the version you are releasing.
+   command: `@JuliaRegistrator register branch=release-15.0.0`, modifying as appropriate
+   for the version you are releasing.
 
 If there is subsequently a need to increment the version of a dependency, this
 should be done via a new release that follows the above process, and modifies
@@ -34,15 +29,17 @@ should be preferred. If the new release branch is branched from master, *it
 needs to ensure Project.toml caps are all ≥ to those listed in the previous
 Catalyst release branch*.
 
-## Development advice
+## [Development advice](@id devdocs_advice)
 
-### Checking doc builds for errors
+### [Checking doc builds for errors](@id devdocs_advice_doc_error_checks)
 When updating documentation, Catalyst will run any Julia code provided within example blocks to dynamically create figures and outputs. In addition to automatically creating these for us, it also provides an automatic check that all code in documentation is correct. Here, if any of the documentation code throws an error, the build job will fail. The documentation build job can be found at the bottom of a PRs conversation, here is an example of a failed one:
+
 ![Failed builddocs link](../assets/devdocs/failed_builddocs_link.png)
+
 To check what errors were produced, click on the "Details" link of the job. Next, any errors can be found at the bottom of the "Build and deploy" section (which should be opened automatically).
 
-### Inspecting documentation of a PR or branch
-When updating documentation it is typically useful to view the updated documentation in HTML format (which is the format users will see). Here, some errors are much easier to spot in html format as compared with the raw text files from which these are generated. There are two primary ways to view updated documentation, either by downloading them from the PR or by building the docs locally.
+### [Inspecting the built documentation of a PR or branch](@id devdocs_advice_doc_inspection)
+When updating documentation it is typically useful to view the updated documentation in HTML format (which is the format users will see). Here, some errors are much easier to spot in .html format as compared with the raw text files from which these are generated. There are two primary ways to view updated documentation, either by downloading them from the PR or by building the docs locally.
 
 Whenever a PR to Catalyst is created, CI will create a corresponding documenter build job. If the build job passes, you can access the built documentation (which will be the new Catalyst documentation if the PR is merged) through the following steps:
 1. Click on "Details" in the documentation build job (at the bottom of the PR conversation tab). 
@@ -54,5 +51,5 @@ To build the Catalyst documentation locally:
 1. Navigate to the ".julia/dev/Catalyst/docs/" folder and run the "make.jl" file using ">julia make.jl". Alternatively, open a Julia session, activate the "docs" environment, and run the file using `include("make.jl").
 2. Open the ".julia/dev/Catalyst/docs/build/index.html" file.
 
-### Spellchecking in your code
+### [Spellchecking in your code](@id devdocs_advice_codespellchecker)
 Especially when writing documentation, but also when writing normal code, it can be useful to have a spellchecker running through your texts. While code can be copied into a spellchecker and checked there (which is still useful to check grammar), it can also be very useful to (for users of VSCode) run the [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) extension. This will automatically provide simple spell-checking for code and documentation as you write it.

docs/src/index.md

@@ -164,9 +164,9 @@ model. Here we instead show how various Catalyst features can compose to create
 a much more advanced model. Our model describes how the volume of a cell ($V$)
 is affected by a growth factor ($G$). The growth factor only promotes growth
 while in its phosphorylated form ($G^P$). The phosphorylation of $G$ ($G \to G^P$)
-is promoted by sunlight (modeled as the cyclic sinusoid $k_a (\sin(t) + 1)$),
-which phosphorylates the growth factor (producing $G^P$). When the cell reaches a
-critical volume ($V_m$) it undergoes cell division. First, we declare our model:
+is promoted by sunlight, which is modeled as the cyclic sinusoid $k_a (\sin(t) + 1)$.
+When the cell reaches a critical volume ($V_m$) it undergoes cell division. First, we 
+declare our model:
 ```@example home_elaborate_example
 using Catalyst
 cell_model = @reaction_network begin

docs/src/inverse_problems/behaviour_optimisation.md

@@ -1,4 +1,4 @@
-# [Optimization for non-data fitting purposes](@id behaviour_optimisation)
+# [Optimization for Non-data Fitting Purposes](@id behaviour_optimisation)
 In previous tutorials we have described how to use [PEtab.jl](@ref petab_parameter_fitting) and [Optimization.jl](@ref optimization_parameter_fitting) for parameter fitting. This involves solving an optimisation problem (to find the parameter set yielding the best model-to-data fit). There are, however, other situations that require solving optimisation problems. Typically, these involve the creation of a custom objective function, which minimizer can then be found using Optimization.jl. In this tutorial we will describe this process, demonstrating how parameter space can be searched to find values that achieve a desired system behaviour. Many options used here are described in more detail in [the tutorial on using Optimization.jl for parameter fitting](@ref optimization_parameter_fitting). A more throughout description of how to solve these problems is provided by [Optimization.jl's documentation](https://docs.sciml.ai/Optimization/stable/) and the literature[^1].
 
 ## [Maximising the pulse amplitude of an incoherent feed forward loop](@id behaviour_optimisation_IFFL_example)

docs/src/model_creation/chemistry_related_functionality.md

@@ -1,4 +1,4 @@
-# [Chemistry-related functionality](@id chemistry_functionality)
+# [Chemistry-related Functionality](@id chemistry_functionality)
 
 While Catalyst has primarily been designed around the modelling of biological systems, reaction network models are also common in chemistry. This section describes two types of functionality, that while of general interest, should be especially useful in the modelling of chemical systems.
 - The `@compound` option, which enables the user to designate that a specific species is composed of certain subspecies.

docs/src/model_creation/conservation_laws.md

@@ -1,4 +1,4 @@
-# [Working with conservation laws](@id conservation_laws)
+# [Working with Conservation Laws](@id conservation_laws)
 Catalyst can detect, and eliminate for differential-equation based models, *conserved quantities*, i.e. linear combinations of species which are conserved via the chemistry. This functionality is both automatically utilised by Catalyst (e.g. to [remove singular Jacobians during steady state computations](@ref homotopy_continuation_conservation_laws)), but is also available for users to utilise directly (e.g. to potentially [improve simulation performance](@ref ode_simulation_performance_conservation_laws)).
 
 To illustrate conserved quantities, let us consider the following [two-state](@ref basic_CRN_library_two_states) model: