Discuss guidelines for mathematical content in docstrings

[munechika-koyo]

Context

PR #515 improves Sphinx and reStructuredText formatting across API docstrings and the documentation. During review, concerns were raised that markup which renders well in HTML can make docstrings harder to read in source code and through help() in a Python REPL.

There is also a broader question about equation-heavy docstrings: detailed mathematical expressions and derivations may be more useful in the relevant pages under docs/, while docstrings can focus on the API and link to that material.

This issue is intended to agree on the approach before revisiting #515.

Points to discuss

• How should we balance typographical/semantic correctness in rendered HTML against readability of raw docstrings?
• When should superscripts and subscripts use Unicode characters (for example, m⁻³ or nₑ) rather than reStructuredText or LaTeX markup?
• Should docstrings containing LaTeX be raw strings (r"""...""") to avoid doubled backslashes?
• How much mathematical detail belongs in a docstring?
• When equations or derivations are moved to docs/, how should docstrings reference the corresponding documentation section?

Possible direction

• Keep docstrings focused on how to use the API: parameters, return values, behavior, caveats, and concise examples.
• Keep short equations in docstrings when they materially help explain the API, possibly in a Notes section.
• Move long equations and derivations to an appropriate page under docs/ and add a cross-reference from the docstring.
• Prefer readable Unicode superscripts/subscripts for common units and simple notation where the characters are available and unambiguous.
• Prefer semantic reStructuredText/LaTeX formatting in documentation pages that are primarily consumed as rendered HTML.

Origin

Raised by @jacklovell in the review discussion on #515, particularly this comment. See also the preceding readability discussion.

[jacklovell]

Thanks for raising this @munechika-koyo. I like the following principles:

1. Docstrings should be human-readable without any extra processing since they'll likely be seen in raw form in source code editors and Python REPL/Jupyter notebooks when users work with the code.
2. Where semantic correctness (e.g. using the typographically-correct LaTeX tags) hurts readability, the more human-readable but less semantically-correct version should be used in docstrings. This includes using unicode superscripts/subscripts instead outside of LaTeX :math: blocks instead of other formatting directives like :sup:, and omitting \mathrm{} and \left(/\right) where possible.
3. The HTML documentation (which is stored as reStructuredText source files in the ./docs directory in the repository) should be produced using semantically-correct RST - and this extends to semantically-correct LaTeX in :math: blocks where possible. The RST source files are not intended to be user-facing: the built HTML is.
4. Docstrings should inform users how to use the class/function/module being documented. The mathematical foundations/models/cited literature sources should be placed in an RST file in the documentation.
5. The use of :autoclass:, :automethod: etc to populate documentation pages with docstrings should be used alongside writing RST documentation in the docs: including all information about a model etc. in a docstring should not be used as a way to avoid writing dedicated documentation for a feature.

I suspect that if we move most of the heavy algebra out of docstrings will help resolve many instances of (2) and (3).