doc: Move description for math confval, directives and roles to usage

doc/usage/restructuredtext/directives.rst

@@ -1005,9 +1005,63 @@ this reason, the following directive exists:
 Math
 ----
 
-.. todo:: Move this in here.
+The input language for mathematics is LaTeX markup.  This is the de-facto
+standard for plain-text math notation and has the added advantage that no
+further translation is necessary when building LaTeX output.
 
-See :ref:`math-support`.
+Keep in mind that when you put math markup in **Python docstrings** read by
+:mod:`autodoc <sphinx.ext.autodoc>`, you either have to double all backslashes,
+or use Python raw strings (``r"raw"``).
+
+.. rst:directive:: math
+
+   Directive for displayed math (math that takes the whole line for itself).
+
+   The directive supports multiple equations, which should be separated by a
+   blank line::
+
+      .. math::
+
+         (a + b)^2 = a^2 + 2ab + b^2
+
+         (a - b)^2 = a^2 - 2ab + b^2
+
+   In addition, each single equation is set within a ``split`` environment,
+   which means that you can have multiple aligned lines in an equation,
+   aligned at ``&`` and separated by ``\\``::
+
+      .. math::
+
+         (a + b)^2  &=  (a + b)(a + b) \\
+                    &=  a^2 + 2ab + b^2
+
+   For more details, look into the documentation of the `AmSMath LaTeX
+   package`_.
+
+   When the math is only one line of text, it can also be given as a directive
+   argument::
+
+      .. math:: (a + b)^2 = a^2 + 2ab + b^2
+
+   Normally, equations are not numbered.  If you want your equation to get a
+   number, use the ``label`` option.  When given, it selects an internal label
+   for the equation, by which it can be cross-referenced, and causes an equation
+   number to be issued.  See :rst:role:`eq` for an example.  The numbering
+   style depends on the output format.
+
+   There is also an option ``nowrap`` that prevents any wrapping of the given
+   math in a math environment.  When you give this option, you must make sure
+   yourself that the math is properly set up.  For example::
+
+      .. math::
+         :nowrap:
+
+         \begin{eqnarray}
+            y    & = & ax^2 + bx + c \\
+            f(x) & = & x^2 + 2xy + y^2
+         \end{eqnarray}
+
+.. _AmSMath LaTeX package: https://www.ams.org/publications/authors/tex/amslatex
 
 
 Grammar production displays

doc/usage/restructuredtext/roles.rst

@@ -277,6 +277,26 @@ The following role creates a cross-reference to a term in a
    during build.
 
 
+Math
+----
+
+.. rst:role:: math
+
+   Role for inline math.  Use like this::
+
+      Since Pythagoras, we know that :math:`a^2 + b^2 = c^2`.
+
+.. rst:role:: eq
+
+   Role for cross-referencing equations via their label.  Example::
+
+      .. math:: e^{i\pi} + 1 = 0
+         :label: euler
+
+      Euler's identity, equation :eq:`euler`, was elected one of the most
+      beautiful mathematical formulas.
+
+
 Other semantic markup
 ---------------------