LaTeX equations in documentation

[VeckoTheGecko]

Now that we have support for LaTeX in API documentation (8b4d5695d9f51482e769fa4904aaabc0f1891e70), it would be good to improve some of the documentation accordingly.

For starters, adding LaTeX equations detailing the implementation of (some of) the advection kernels would be good. For AdvectionRK4 I came up with the following equation (going from the code implementation, and looking at some supplementary info on RK integration schemes). Mainly just including to show the notation I'm using.

followup:

• Are the implementations of the advection kernels discussed in any tutorial notebooks (I couldn't find any, but just checking my bases)
• Are the implementations of the advection kernels discussed in any research papers? (happy to add them as reference in the docstrings). It would good to make sure that the mathematical notation align between the docstring and the papers which discuss it.
• Are there other parts of the documentation that can benefit from having LaTeX equations to help explain?

[erikvansebille]

Thanks for this suggestion, @VeckoTheGecko. Yes, I guess it could make sense to add LaTeX equations for the (advection) application kernels.

Although I think that RK4 in particular is so standard, that many readers will know it. And even if they don't, then what is the benefit of showing LaTeX equations over the python-code itself? it's not too hard to read? And at least users don't need to worry about inconsistencies between the documentation and the code.

So while I like the idea of being able to add LaTeX to documentation, I'm not sure whether RK4 is the most obvious place to start

[VeckoTheGecko]

I'm not sure whether RK4 is the most obvious place to start

Yeah. I agree. I can sometimes get a bit ahead of myself; best to focus on things that will provide tangible benefit 😄 . Instead, are there any texts you'd suggest that can be linked to provide more info surrounding integration schemes like RK4? Just in case someone is unfamiliar and wants to learn more.

Are there any parts of the documentation that you think could benefit from having LaTeX?

[erikvansebille]

Well, the Wikipedia page on Runge-Kutta methods is pretty good and clear: https://en.wikipedia.org/wiki/Runge–Kutta_methods

LaTeX might benefit the diffusion kernels, following the notebook at https://nbviewer.jupyter.org/github/OceanParcels/parcels/blob/master/parcels/examples/tutorial_diffusion.ipynb

[erikvansebille]

The LaTeX in the read-the-docs seems to work fine (see e.g. https://docs.oceanparcels.org/en/latest/examples/tutorial_diffusion.html), and extra equations are not too relevant now as discussed above; so am closing for now