Repository navigation
Discuss guidelines for mathematical content in docstrings #516
Description
Activity
Thanks for raising this @munechika-koyo. I like the following principles:
- 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.
- 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. - The HTML documentation (which is stored as reStructuredText source files in the
./docsdirectory 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. - 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.
- 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).
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
m⁻³ornₑ) rather than reStructuredText or LaTeX markup?r"""...""") to avoid doubled backslashes?docs/, how should docstrings reference the corresponding documentation section?Possible direction
Notessection.docs/and add a cross-reference from the docstring.Origin
Raised by @jacklovell in the review discussion on #515, particularly this comment. See also the preceding readability discussion.