Merge branch 'stable'

doc/ext/math.rst

@@ -1,5 +1,7 @@
 .. highlight:: rest
 
+.. _math-support:
+
 Math support in Sphinx
 ======================
 
@@ -231,10 +233,14 @@ Sphinx.
    The path to the JavaScript file to include in the HTML files in order to load
    MathJax.
 
-   The default is the ``http://`` URL that loads the JS files from the `MathJax
-   CDN <http://docs.mathjax.org/en/latest/start.html>`_.  If you want MathJax to
-   be available offline, you have to download it and set this value to a
-   different path.
+   The default is the ``https://`` URL that loads the JS files from the
+   `cdnjs`__ Content Delivery Network. See the `MathJax Getting Started
+   page`__ for details. If you want MathJax to be available offline, you have
+   to download it and set this value to a different path.
+
+   __ https://cdjns.com
+
+   __ http://docs.mathjax.org/en/latest/start.html
 
    The path can be absolute or relative; if it is relative, it is relative to
    the ``_static`` directory of the built docs.

doc/markup/misc.rst

@@ -210,7 +210,17 @@ Including content based on tags
 Tables
 ------
 
-Use :ref:`standard reStructuredText tables <rst-tables>`.  They work fine in
+Use :ref:`reStructuredText tables <rst-tables>`, i.e. either
+
+- grid table syntax (:duref:`ref <grid-tables>`),
+- simple table syntax (:duref:`ref <simple-tables>`),
+- :dudir:`csv-table` syntax,
+- or :dudir:`list-table` syntax.
+
+The :dudir:`table` directive serves as optional wrapper of the *grid* and
+*simple* syntaxes.
+
+They work fine in
 HTML output, however there are some gotchas when using tables in LaTeX: the
 column width is hard to determine correctly automatically.  For this reason, the
 following directive exists:
@@ -313,6 +323,11 @@ following directive exists:
       Sphinx's merged cells interact well with ``p{width}``, ``\X{a}{b}``, ``Y{f}``
       and tabulary's columns.
 
+Math
+----
+
+See :ref:`math-support`.
+
 .. rubric:: Footnotes
 
 .. [#] For most builders name and format are the same. At the moment only

doc/rest.rst

@@ -159,7 +159,7 @@ rendered as "The next paragraph is a code sample:".
 Tables
 ------
 
-Two forms of tables are supported.  For *grid tables* (:duref:`ref
+For *grid tables* (:duref:`ref
 <grid-tables>`), you have to "paint" the cell grid yourself.  They look like
 this::
 
@@ -173,7 +173,7 @@ this::
    +------------------------+------------+----------+----------+
 
 *Simple tables* (:duref:`ref <simple-tables>`) are easier to write, but
-limited: they must contain more than one row, and the first column cannot
+limited: they must contain more than one row, and the first column cells cannot
 contain multiple lines.  They look like this::
 
    =====  =====  =======
@@ -185,6 +185,8 @@ contain multiple lines.  They look like this::
    True   True   True
    =====  =====  =======
 
+Two more syntaxes are supported: *CSV tables* and *List tables*. They use an
+*explicit markup block*, see `Directives`_ section.
 
 Hyperlinks
 ----------