Docs housekeeping

[TorkelE]

• Fixes a spelling mistake.
• Changes usage of → to -->.
• Adds in figure files that somehow was missing from the PEtab doc, sorry about that.

[isaacsas]

Why aren't the figures being generated dynamically as an example block?

[TorkelE]

I have an example block before. However, given that it is re-run every time the docs happen, and that there is a potential chance that the parameter fitting fails (possible especially when we make the initial example using a single run), making the doc look funny, I simply pasted in output figures from a run I made. That way there is no risk they change every time.

[isaacsas]

But if that is the case isn't this a bad example to ask a new user to try running themselves? If they run it and it fails they will likely be quite confused and assume they've made a mistake.

[TorkelE]

If it was an example where that happened frequently, I would agree. I just did 25 runs of the fitting and they all turned out fine, this is mostly me being paranoid. Ideally (and especially for difficult problems) one should use multistart-optimization, however, I wanted to build things up from the beginning with the simplest case, and not overload the user. If you want I could add a note of this.

[TorkelE]

I do not understand this issue on the 1.6 CI that has started to pop-up:

Otherwise, this is all good to go now.

[isaacsas]

Looks like CI is passing now, but I would still strongly prefer we keep example code as @examples as done in most of the rest of the docs. If you need a deterministic answer can you not set the random number seed and use StableRNGs? You could mention this choice is just to ensure the simulation gives the same result in the docs as the fitting involves randomness as setup, and users should just skip it (or hide that code block from users).

I just think we get a lot of value from being able to see that a doc is suddenly not working, which we lose when things aren’t @examples blocks.

[TorkelE]

So, I definitely agree that the automatic testing that @example provides is invaluable, and we were burned before that system was put in place. I will think if I can make it possible for the first case. I tried to maintain @example where possible (even if I set the display myself) to catch errors at least. There are however some cases like:

using Optim
using QuasiMonteCarlo
res_ms = calibrate_model_multistart(petab_problem, IPNewton(), 10, "OptimizationRuns"; sampling_method=QuasiMonteCarlo.SobolSample())

where the code actually saves the output to a file. I did not want our doc code to start saving stuff to the documentation, hence this was disabled.
(later on I also load stuff from this "file", which for the same reason I disabled)

[isaacsas]

If the files are small we could have them saved into the assets folder dynamically. But I’m ok with files that are saved or loaded being premade. I’d prefer figures are dynamic though since they are easy to scan to see doc problems.

[isaacsas]

Typically I find problems by noticing the absence of figures…

[TorkelE]

yeah, this way it is only really showing up in the doc logs when you happen to have a look at it, so def not perfect (and there might also be problems that do not involve throwing an error as well)

[TorkelE]

If the files are small we could have them saved into the assets folder dynamically. But I’m ok with files that are saved or loaded being premade. I’d prefer figures are dynamic though since they are easy to scan to see doc problems.

I could add a hidden line that directly deletes the generated folder
(PEtab doesn't overwrite, so will keep adding sub files to the target folder each time it is run)

[isaacsas]

Yes, we don't want to keep adding new folders everytime this runs within the doc hierarchy. If you can tell PETab where to create it though you can just use tempname to have Julia give you a temporary name that should get cleaned up (but it shouldn't get saved on the Github website branch).

[isaacsas]

Or make sure to delete and overwrite the old sub files/folders.

[TorkelE]

I could add a hidden line (before the line which saves the data to the folder), which create the folder (and then delete the folder later in the routine.

[isaacsas]

Sure

[TorkelE]

Updated (but just want to check that it all builds nicely before merging).