Getting multiline docstring equations to be displayed in Sphinx. Potential bug in Sphinx?

Question

There is the following piece of code on the official Sphinx documentation:

.. math::
   :nowrap:

   \begin{eqnarray}
   y    & = & ax^2 + bx + c \\
   f(x) & = & x^2 + 2xy + y^2
   \end{eqnarray}

I tried for a long time to get it to work, until I changed it to:

.. math::
   :nowrap:

   $$
   \\begin{eqnarray}
   y    & = & ax^2 + bx + c \\\\
   f(x) & = & x^2 + 2xy + y^2
   \\end{eqnarray}
   $$

How could it be that the official Sphinx documentation is wrong? Or is something obscure happening here? Even Sagemath documentation seems to suggest that $$ need to be used (see "If you wish to explicitly not wrap the MATH block [...]") Or is this a bug?

(I use Sphinx 2.2.0 and in my index.rst file I use autofunction for the function whose docstring contains the equation above.)

Answer 1

The Sphinx documentation states that when you put math markup in Python docstrings read by autodoc, you either have to double all backslashes, or use Python raw strings (r"raw"). That happens because Python will interpret the string before Sphinx has the opportunity to parse it.

So, if you want to insert math in a docstring, the following should work:

.. math::
   :nowrap:

   \\begin{eqnarray}
   y    & = & ax^2 + bx + c \\\\
   f(x) & = & x^2 + 2xy + y^2
   \\end{eqnarray}

You may simplify it further with:

.. math::

   y    & = ax^2 + bx + c \\\\
   f(x) & = x^2 + 2xy + y^2

The :nowrap only hints Sphinx that it should not wrap the provided equations in a LaTeX "split" environment (See Section 3 of the amsmath Manual). Instead, you must supply your own as indicated in the first example of this post.