Merge branch 'master' into 789_escape_braces_on_samp_role

doc/usage/markdown.rst

@@ -0,0 +1,47 @@
+.. highlight:: python
+
+.. _markdown:
+
+========
+Markdown
+========
+
+`Markdown`__ is a lightweight markup language with a simplistic plain text
+formatting syntax.  It exists in many syntactically different *flavors*.  To
+support Markdown-based documentation, Sphinx can use `recommonmark`__.
+recommonmark is a Docutils bridge to `CommonMark-py`__, a Python package for
+parsing the `CommonMark`__ Markdown flavor.
+
+__ https://daringfireball.net/projects/markdown/
+__ https://recommonmark.readthedocs.io/en/latest/index.html
+__ https://github.com/rtfd/CommonMark-py
+__ http://commonmark.org/
+
+Configuration
+-------------
+
+To configure your Sphinx project for Markdown support, proceed as follows:
+
+#. Install *recommonmark*::
+
+      pip install recommonmark
+
+#. Add the Markdown parser to the ``source_parsers`` configuration variable in
+   your Sphinx configuration file::
+
+      source_parsers = {
+         '.md': 'recommonmark.parser.CommonMarkParser',
+      }
+
+   You can replace ``.md`` with a filename extension of your choice.
+
+#. Add the Markdown filename extension to the  ``source_suffix`` configuration
+   variable::
+
+      source_suffix = ['.rst', '.md']
+
+#. You can further configure *recommonmark* to allow custom syntax that
+   standard *CommonMark* doesn't support. Read more in the `recommonmark
+   documentation`__.
+
+__ https://recommonmark.readthedocs.io/en/latest/auto_structify.html

doc/usage/quickstart.rst

@@ -236,7 +236,8 @@ so on.  The file is saved in UTF-8 by default, as indicated by the encoding
 declaration in the first line.  If you use non-ASCII characters in any string
 value, you need to use Python Unicode strings (like ``project = u'Exposé'``).
 
-|more| See :ref:`build-config` for documentation of all available config values.
+|more| See :doc:`/usage/configuration` for documentation of all available
+config values.
 
 
 .. todo:: Move this entire doc to a different section

doc/usage/restructuredtext/basics.rst

@@ -1,4 +1,4 @@
-.. highlightlang:: rst
+.. highlight:: rst
 
 .. _rst-primer:
 

doc/usage/restructuredtext/field-lists.rst

@@ -1,4 +1,4 @@
-.. highlightlang:: rst
+.. highlight:: rst
 
 ===========
 Field Lists