Improve documentation on completeness.

Author: TorkelE

docs/src/catalyst_functionality/compositional_modeling.md

@@ -5,7 +5,7 @@ can construct the earlier repressilator model by composing together three
 identically repressed genes, and how to use compositional modeling to create
 compartments.
 
-## A note on *completeness*
+## [A note on *completeness*](@id completeness_note)
 Catalyst `ReactionSystem` can either be *complete* or *incomplete*. When created using the `@reaction_network` DSL they are *created as complete*. Here, only complete `ReactionSystem`s can be used to create the various problem types (e.g. `ODEProblem`). However, only incomplete `ReactionSystem`s can be composed using the features described below. Hence, for compositional modeling, `ReactionSystem` must be created as incomplete, and later set to complete before simulation.
 
 To create incomplete `ReactionSystem`s using the DSL as complete, use the `@network_component` instead of `@reaction_network`:
@@ -15,13 +15,13 @@ degradation_component = @network_component begin
   d, X --> 0
 end
 ```
-Or when created directly, use the `complete = false` argument:
+Alternatively all `ReactionSystem`s created programmatically are incomplete:
 ```@example ex0
 @parameters d
 @variable t
 @species X(t)
 rx = Reaction(d, [X], nothing)
-@named degradation_component = ReactionSystem([rs], t; complete = false)
+@named degradation_component = ReactionSystem([rs], t)
 ```
 We can test whether a system is complete using the `ModelingToolkit.iscomplete` function:
 ```@example ex0
@@ -83,7 +83,7 @@ t = default_t()
 @parameters k
 @species A(t), B(t), C(t)
 rxs = [Reaction(k, [A,B], [C])]
-@named rn = ReactionSystem(rxs, t; systems = [newrn, newestrn], complete = false)
+@named rn = ReactionSystem(rxs, t; systems = [newrn, newestrn])
 ```
 
 Catalyst provides several different accessors for getting information from a
@@ -147,7 +147,7 @@ t = default_t()
 @named G1 = repressed_gene(; R=ParentScope(G3₊P))
 @named G2 = repressed_gene(; R=ParentScope(G1.P))
 @named G3 = repressed_gene(; R=ParentScope(G2.P))
-@named repressilator = ReactionSystem(t; systems=[G1,G2,G3], complete = false)
+@named repressilator = ReactionSystem(t; systems=[G1,G2,G3])
 ```
 Notice, in this system each gene is a child node in the system graph of the repressilator
 ```julia

docs/src/catalyst_functionality/programmatic_CRN_construction.md

@@ -61,6 +61,9 @@ system to be the same as the name of the variable storing the system.
 Alternatively, one can use the `name = :repressilator` keyword argument to the
 `ReactionSystem` constructor.
 
+!!! warn
+       All `ReactionSystem`s created programmatically (i.e. by calling `ReactionSystem` with some input, rather than using `@reaction_network`) are created as *incomplete*. To simulate them, they must first be made *complete*. This can be done using the `complete` function, i.e. by calling `repressilator = complete(repressilator)`. An expanded description on *completeness* can be found [here](@ref completeness_note).
+
 We can check that this is the same model as the one we defined via the DSL as
 follows (this requires that we use the same names for rates, species and the
 system)

docs/src/introduction_to_catalyst/introduction_to_catalyst.md

@@ -96,6 +96,7 @@ Let's now use our `ReactionSystem` to generate and solve a corresponding mass
 action ODE model. We first convert the system to a `ModelingToolkit.ODESystem`
 by
 ```@example tut1
+repressilator = complete(repressilator)
 odesys = convert(ODESystem, repressilator)
 ```
 (Here Latexify is used automatically to display `odesys` in Latex within Markdown
@@ -138,6 +139,7 @@ By passing `repressilator` directly to the `ODEProblem`, Catalyst has to
 (internally) call `convert(ODESystem, repressilator)` again to generate the
 symbolic ODEs. We could instead pass `odesys` directly like
 ```@example tut1
+odesys = complete(odesys)
 oprob2 = ODEProblem(odesys, u₀symmap, tspan, psymmap)
 nothing   # hide
 ```
@@ -152,6 +154,10 @@ underlying problem.
     always be converted to `symbolic` mappings using [`symmap_to_varmap`](@ref),
     see the [Basic Syntax](@ref basic_examples) section for more details.
 
+
+!!! note
+    Above we have used `repressilator = complete(repressilator)` and `odesys = complete(odesys)` to mark these systems as *complete*. This must be done before any system is given as input to a `convert` call or some problem type. Models created through the @reaction_network` DSL (which is introduced elsewhere, and primarily used throughout these documentation) are created as complete. Hence `complete` does not need to be called on these models. An expanded description on *completeness* can be found [here](@ref completeness_note).
+
 At this point we are all set to solve the ODEs. We can now use any ODE solver
 from within the
 [DifferentialEquations.jl](https://docs.sciml.ai/DiffEqDocs/stable/solvers/ode_solve/)