documentation improvements

[Mo-Gul]

Feel free to cherry-pick.

Now follow some open questions or open points which I summarize here as tasks, so they can be checked when done.

• (Code) Spell Checker
• missing link destination
• LaTeX stuff
  • $ syntax
  • $$ syntax
• line breaks vs. no line breaks
• other/wrong ref/cite style
  • No footnote syntax
  • Ref [1] not used
  • Link in references are no links
• markdownlint (VS Code) issues
  • MD001/heading-increment
  • MD025/single-title/single-h1
  • MD029/ol-prefix
  • MD045/no-alt-text
  • MD059/descriptive-link-text

(Code) Spell Checker

You write to use a spell checker,

Catalyst.jl/docs/src/devdocs/dev_guide.md

Lines 54 to 55 in 64c117f

### [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.

but I can't find a dictionary file in the repo for all the unknown words. Is that intended?

missing link destination

In

Catalyst.jl/docs/src/steady_state_functionality/dynamical_systems.md

Line 94 in 64c117f

Next, we consider the [Brusselator] model. First we simulate the model for two similar initial conditions, confirming that they converge to the same limit cycle:

[Brusselator] should either be [Brusselator](@ref basic_CRN_library_brusselator) or [Brusselator](https://en.wikipedia.org/wiki/Brusselator).

LaTeX stuff

$ syntax

When I am not mistaken, the $ syntax shouldn't be used (any more), right? But there are plenty of (remaining) instances like

Catalyst.jl/docs/src/introduction_to_catalyst/catalyst_for_new_julia_users.md

Line 80 in 64c117f

Here, we create a simple [*birth-death* model](@ref basic_CRN_library_bd), where a single species ($X$) is created at rate $b$, and degraded at rate $d$. The model is stored in the variable `rn`.

Instead, according to the "Markdown LaTeX" section of the Julia manual the double backtick syntax should be used ``.

Is it intentional that some files still use the $ syntax?

$$ syntax

There also is one remaining instance of $$ at

Catalyst.jl/docs/src/model_creation/examples/hodgkin_huxley_equation.md

Line 29 in 64c117f

$$s' \xleftrightarrow[\beta_s(V(t))]{\alpha_s(V(t))} s, \quad s \in \{m,n,h\}$$

which should be replaced with a ```` math block fenced block.

line breaks vs. no line breaks

Some files don't have line breaks inside paragraphs -- like the Introduction to Catalyst and Julia for New Julia users) --, but some file have -- like the following file/section Introduction to Catalyst.

Should this be harmonized? And if yes, to which style?

other/wrong ref/cite style

Please have a look at the "Smoluchowski Coagulation Equation" section.

No footnote syntax

There isn't used the "footnote" syntax for the references and the citations ([^1]). This is the only (remaining) file with such a style.

Ref [1] not used

Currently the link is given directly at each entry, but there is no "[1]" in the text. So when you don't switch to the "footnote" syntax, either add it somewhere in the text or remove the entry.

Link in references are no links

The title says it all, but to be sure, here (also) a picture of the current output

(Remaining) markdownlint (VS Code) issues

MD001/heading-increment

Please check if the number of # is really correct.

Catalyst.jl/docs/src/inverse_problems/global_sensitivity_analysis.md

Line 8 in 64c117f

### [Global vs local sensitivity](@id global_sensitivity_analysis_global_vs_local_sensitivity)

Catalyst.jl/docs/src/model_creation/dsl_basics.md

Line 11 in 64c117f

### [Quick-start summary](@id dsl_description_quick_start)

Catalyst.jl/docs/src/model_simulation/simulation_introduction.md

Line 6 in 64c117f

### [Background to CRN simulations](@id simulation_intro_theory)

Catalyst.jl/docs/src/index.md

Line 20 in 64c117f

#### [Features of Catalyst](@id doc_index_features_catalyst)

Catalyst.jl/docs/src/index.md

Line 132 in 64c117f

#### [Deterministic ODE simulation of Michaelis-Menten enzyme kinetics](@id doc_index_example_ode)

Catalyst.jl/docs/src/v14_migration_guide.md

Line 186 in 64c117f

#### Modification of problems with conservation laws broken

(and the following two headings.)

MD025/single-title/single-h1

Catalyst.jl/docs/src/network_analysis/odes.md

Line 209 in 64c117f

# Full decomposition of the reaction network ODEs (flux matrix and mass-action vector)

MD029/ol-prefix

Catalyst.jl/docs/src/inverse_problems/petab_ode_param_fitting.md

Lines 76 to 84 in 64c117f

	### Measurements
	Finally, we need to define the system measurements to which the parameters will be fitted. Each measurement combines:
	1. The observable which is observed (here we use the id tag defined in the `observables` dictionary).
	2. The time point of the measurement.
	3. The measured value.
	For cases where several simulation conditions are given, we also need to provide:
	4. The simulation condition which generates the measurement ([here](@ref petab_simulation_conditions) is an example where this is used).

shows as

and correspondingly for

Catalyst.jl/docs/src/inverse_problems/petab_ode_param_fitting.md

Lines 426 to 434 in 64c117f

	## [Multi-start optimisation](@id petab_multistart_optimisation)
	To avoid the optimisation process returning a local minimum, it is often advised to run it multiple times, using different initial guesses. PEtab.jl supports this through the `calibrate_multistart` function. This is identical to the `calibrate` function, but takes one additional arguments:
	1. `nmultistarts`: The number of runs to perform.
	And two additional optional argument:
	2. `dirsave`: A location to which the output is automatically saved. If `dirsave=nothing`, no output is saved. It is recommended to save intermediate results for parameter estimation runs that take a long time, to not lose intermediate results if something goes wrong.
	3. `sampling_method`: Selects the sampling method with which to select the initial guesses (`QuasiMonteCarlo.LatinHypercubeSample()` used by default).

According to the "Markdown Lists" section in the Julia manual starting with another number than 1 should work, shouldn't it?

MD045/no-alt-text

The heading says it all :) Here are the instances

Catalyst.jl/docs/src/spatial_modelling/lattice_reaction_systems.md

Line 65 in 64c117f



Catalyst.jl/docs/src/spatial_modelling/lattice_simulation_plotting.md

Line 49 in 64c117f



Catalyst.jl/docs/src/spatial_modelling/lattice_simulation_plotting.md

Line 91 in 64c117f



(Perhaps you could also add a blank line at the end (if it is missing).)

MD059/descriptive-link-text

There are a lot of "[here]" links that should be replaced ... I don't give an example here, because one can simply search for e.g. "[here](" to find them all.

[TorkelE]

I tried to check the changes, but I just see lots and lots of added line breaks, and I'm not sure I really see the use of those.

[Mo-Gul]

As my first sentence of the PR states: Feel free to cherry-pick whatever commits you like.

When you don't like all the added linebreaks, ignore the commits

• docs: MD022/blanks-around-headings
• docs: MD031/blanks-around-fences
• docs: MD032/blanks-around-lists

It is true what when having a look at the result of all the commits at once, you only see the added linebreaks. But you can go through the commits one by one (excluding the above). Most of them are then quite short.

The above mentioned three commits are just fixes of hints from markdownlint (VS Code). to helps to keep a consistent (documentation) style.

[isaacsas]

Thank you for your time and effort on making this PR!

Generally formatting changes should be kept distinct from other changes (i.e. via separate PRs). This makes review feasible and enables us to more easily see what content is actually being changed. If you could open a shorter PR that removes whitespace/formatting commits so we can review the more important changes involving broken links, typos, spelling and such that would be really helpful.

As my first sentence of the PR states: Feel free to cherry-pick whatever commits you like.

Please keep in mind that maintainers of projects can be quite busy, so finding time to cherry pick your commits, open our own PRs with them, and then review them, will likely result in your work languishing an extended amount of time (as will submission of one very long PR with thousands of lines of changes vs. multiple shorter PRs that only change a few hundred lines). If you would like to help facilitate the process please open a PR yourself with formatting related-changes removed.

[isaacsas]

Some guidance about SciML's practices for PRs is at: https://docs.sciml.ai/ColPrac/stable/#Guidance-on-contributing-PRs

[Mo-Gul]

As you can guess my time is also limited. Unfortunately you were a bit too vague what you expect me to do.

Before submitting the PR I already reordered the commits to start with the formatting stuff (starting with MD022, MD031 and MD032). I am not sure why the order given here is different. This has already caused me a lot of conflicts that I had to resolve. (When I remember correctly that is because you don't have much linebreaks in paragraphs, i.e. a paragraph is a single line of text.) I don't want to resolve plenty of conflicts again.

And since I am not a Git expert, I could offer to go back in time in my repo and first submit a new PR with the above three "whitespace" commits. After you have accepted these I think the rest can go in one more PR.

I already have prepared one more PR which is to harmonize the spelling to UK or US, see my branches

• UK-spelling
• US-spelling

Because of my only noob level of git I just made these branches from the HEAD of my master branch, thus they include also all the above commits ...

So please let me know if the suggested way of providing new PRs is OK for you.