Decide how to deal with math in docstrings

[CSchoel]

We currently use two different styles of writing math equations in docstrings:

1. Most functions just use a literal style that is intended to be readable when browsing through the source code:

   delta_n = delta_0 * e^(ln(mu) * n)
   

   • pro
     • Easy to read without any plugins that parse the formatting or requiring to go to the website.
     • Often similar to the code itself.
     • WYSIWYG ⇒ No risk of accidentally introducing parsing errors for docs.
     • Most of nolds already uses this convention.
   • con
     • Can get awkward for more complex formulas, such as large square roots or limits, which need to be written as a function application.
     • Some special characters will still need to be escaped. Not easy to remember which those are in reStructuredText and this also hurts readability.
     • No easy way to ensure alignment of complex formulas.

2. Some functions like nolds.datasets.logistic_map use math blocks that contain LaTeX code:

   .. math::
       |\delta_n| = |\delta_0| e^{\lambda n}
   

   • pro
     • Beautifully rendered math. ✨
     • Very expressive, math can stay close to papers.
     • It is clear what characters need to be escapes, as we follow LaTeX syntax.
   • con
     • Virtually unreadable without extra tools. (This can be a problem since IDEs typically don't understand reST in docstrings to provide documentation popups.)
     • Easy to introduce errors while writing that are not immediately highlighted by the linter.
     • Inline math is quite awkward to type

       :math:`x_n`
       

Since nolds covers a very math-heavy topic, we should ensure that we use the style that facilitates understanding the most and that we keep consistent with it.

DoD

• [ ] Decide on a style to use.
• [ ] Adopt it everywhere it hasn't been adopted yet.
• [ ] (Optional) Try to find solutions to mitigate the downsides of the selected style.

[CSchoel]

Thoughts:

• We could use literal blocks to combat the issue of having to escape "human-readable" math.
• People will probably read the documentation from their IDE at least as often as they use the HTML-formatted docs.
• If users want to read the whole docstring, they'll most likely choose HTML-formatted documentation over plain docstrings from the IDE.
• We could just double each math section and add a reST comment block with the human-readable version, but that would require significant overhead effort.
• We could switch from reST to Markdown or even ditch Sphinx completely for MkDocs.
• We could add a CI step to check for reST validity.
• It seems that VS Code renders markdown in docstrings fairly well.