doc: Add "markdown" section to usage guide

Signed-off-by: Stephen Finucane <stephen@that.guru>

doc/usage/markdown.rst

@@ -0,0 +1,43 @@
+.. highlight:: python
+
+========
+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.
+
+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
+   <shttp://recommonmark.readthedocs.io/en/latest/auto_structify.html>`__.
+
+.. _Markdown: https://daringfireball.net/projects/markdown/
+.. _recommonmark: https://recommonmark.readthedocs.io/en/latest/index.html
+.. _CommonMark-py: <https://github.com/rtfd/CommonMark-py>
+.. _CommonMark: http://commonmark.org/