Bug 1466084 - Docs: Add Sphinx markdown support

We want to switch from reStructuredText to Markdown, since:
* it's more user-friendly
* it is used in multiple places on GitHub, so people are more familiar
  with it / context switching between the two is annoying
* the disadvantages of markdown typically raised as reasons to prefer
  reST either don't apply to our use-case, or are no longer accurate
  with recent tooling/extensions
* switching means we can also later start using mkdocs (which doesn't
  support reST) instead of Sphinx. That change has been kept separate
  to reduce the size of the PR, and to make the comparison between
  the two more fair.

See:
https://docs.readthedocs.io/en/latest/getting_started.html#in-markdown
https://recommonmark.readthedocs.io/en/latest/index.html

docs/conf.py

@@ -1,4 +1,6 @@
 import sphinx_rtd_theme
+from recommonmark.parser import CommonMarkParser
+from recommonmark.transform import AutoStructify
 
 # The master toctree document.
 master_doc = 'index'
@@ -12,3 +14,15 @@ exclude_patterns = ['_build']
 
 html_theme = 'sphinx_rtd_theme'
 html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
+source_parsers = {
+    '.md': CommonMarkParser,
+}
+
+source_suffix = ['.rst', '.md']
+
+
+def setup(app):
+    # Enable additional recommonmark features:
+    # https://recommonmark.readthedocs.io/en/latest/auto_structify.html
+    app.add_transform(AutoStructify)

requirements/docs.txt

@@ -5,3 +5,8 @@
 Sphinx==1.7.6
 sphinx-autobuild==0.7.1
 sphinx-rtd-theme==0.4.1
+# Installing from GitHub since the version on PyPI is 2 years old:
+# https://github.com/rtfd/recommonmark/issues/92
+# ...and we need the fix for:
+# https://github.com/rtfd/recommonmark/issues/51
+https://github.com/rtfd/recommonmark/archive/master.zip