Add notebook rendering to the docs

[raar1]

Adds notebook rendering to the documentation using an mkdocs plugin. Notebooks are now in an examples directory within docs/. The notebooks that are included can be configured in the mkdocs.yml.

Fixes #114

[raar1]

@JoYvBa Have a quick look at the rendering if you like (you can try it locally with mkdocs serve). I don't have the latex stuff rendering properly yet, so I'm looking into that. But if you can think of which notebooks we might want to have here already then please suggest them here. I know you have some new examples in another PR, so we can also wait and include some of those when it's merged.

[JoYvBa]

This looks great, documentation really takes shape like this! Also makes it easier to spot mistakes in the examples. I spotted a few, most of which are easily fixed. There are also some things not rendering properly;

• Full equations are not rendered at all, perhaps same fix as in the background documentation, but that may then not render properly in the notebooks themselves.
• Inline math using $$; still shows the dollar signs and does not convert to math.
• Animations are not shown, and every plot below the %matplotlib magic is not shown either.

Perhaps good idea to merge this after my documentation pull request, then we can do everything right in one go!

[raar1]

Thanks for the review! I managed to get the equations to render, but it looks like the animations will have to wait. As we discussed today, I will merge this now and then we can adapt the documentation PR a bit (I think we agreed we will move animations to a python script, rather than notebook, so perhaps we can get the animations that way instead).

[JoYvBa]

@raar1 Looks good Robin, thanks for getting this to work! Animations will indeed have to be done through regular scripts, their behavior in the notebooks is too volatile. Better have something robust than something that breaks every so often (or specifically here; not rendering at all).

[JaroCamphuijsen]

Looks good @raar1, as we discussed, maybe check whether we can only execute the notebooks when deploying the documentation instead of upon every commit.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[raar1]

There does not appear to be any way to pass the parameters to the commandline tool (especially not a parameter of a plugin). So I think the only way to do this is to add a CI step that modifies the mkdocs.yml to set that execute parameter to false, only during docs test builds.

I've done this with a python script that does at least some checks (so it's slightly less hacky...)