Describe best practices for representing equations in docstrings

[namurphy]

A question brought up by Grant Stephens at the PyHC meeting today was: what are the best practices for including equations in docstrings? It'd be helpful to add to our standards a discussion of what the best practices are. If anyone has thoughts or ideas, please add them below. Thanks!

Some points made in the discussion were (if I remember correctly):

• LaTeX is used commonly in docstrings in PyHC packages.
• Mostly scientists will be reading the docstrings, and they tend to be used to LaTeX formatting.
• We also can use unicode characters directly so that equations show up better in docstrings, but that approach doesn't work for more complicated LaTeX constructs like \frac and \int, etc.

Relatedly...tools like MathJax are designed to both render equations graphically in different ways and also improve screen reader (text to speech) compatibility of math.

[namurphy]

Tentatively closing this since we should probably depend on external resources for more information, and the best tools for this tend to change over time.