Using '\displaymath' directives in docstrings formulas

Question

I am using the Sphinx documentation package to document a small Python tool kit that I am working on and I would like to describe the mathematical formulas that the various modules implement by listing them in LaTeX format in the Python docstrings.

It is pretty easy to achieve this with :math: or .. math:: directives for reStructuredText, for example:

.. math::
   \\displaymath \\sum_{i=1}^{\\infty} x_{i}

but the \\displaymath directive is just highlighted as red text when in a Python docstring. When used in a .rst file (e.g. index.rst) this works as expected, and the sub- and super-scripts for the summation are directly below and above the summation symbol.

Is this simply not supported for docstrings, or am I doing something wrong or not doing something that I need to be doing?

Answer 1

You do not need \displaymath in Sphinx and no additional escaping backslashes for \sum and \infty.

The following example function renders fine in both html and latex output when called with .. autofunction:::

def test_func(x):
    """This function will try to calculate:

    .. math::
        \sum_{i=1}^{\\infty} x_{i}

    good luck!
    """
    pass

You have to use the .. math:: directive as inline math (:math:) doesn't work.