Switch Sphinx markdown parser to myst-parser

Switch the markdown parser to the one recommended by the current Sphinx
documentation [1].

This fixes an error parsing Markdown code blocks in `adr-003.md` when
running `make checkdocs` and makes this file show up under "Architecture
Decision Records" in the generated docs.

The `requirements/docs.txt` file was updated by directly running
`.tox/docs/bin/pip-compile -r requirements/docs.in`.

[1] https://www.sphinx-doc.org/en/master/usage/markdown.html

docs/conf.py

@@ -15,8 +15,6 @@
 import os
 # import sys
 
-from recommonmark.parser import CommonMarkParser
-
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
@@ -37,17 +35,13 @@ on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinx.ext.todo', 'sphinx.ext.intersphinx']
+extensions = ['myst_parser', 'sphinx.ext.todo', 'sphinx.ext.intersphinx']
 
 intersphinx_mapping = {'h': ('https://h.readthedocs.io/en/latest/', None)}
 
 # Add any paths that contain tempates here, relative to this directory.
 templates_path = ['_templates']
 
-source_parsers = {
-    '.md': CommonMarkParser,  # Add Markdown support to Sphinx.
-}
-
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #

requirements/docs.in

-recommonmark
+myst-parser
 sphinx-autobuild
 sphinx
-sphinx_rtd_theme
+sphinx_rtd_theme
\ No newline at end of file

requirements/docs.txt

@@ -6,6 +6,8 @@
 #
 alabaster==0.7.12
     # via sphinx
+attrs==20.3.0
+    # via markdown-it-py
 babel==2.9.1
     # via sphinx
 certifi==2020.12.5
@@ -14,11 +16,9 @@ chardet==4.0.0
     # via requests
 colorama==0.4.4
     # via sphinx-autobuild
-commonmark==0.9.1
-    # via recommonmark
 docutils==0.16
     # via
-    #   recommonmark
+    #   myst-parser
     #   sphinx
     #   sphinx-rtd-theme
 idna==2.10
@@ -26,11 +26,21 @@ idna==2.10
 imagesize==1.2.0
     # via sphinx
 jinja2==2.11.3
-    # via sphinx
+    # via
+    #   myst-parser
+    #   sphinx
 livereload==2.6.3
     # via sphinx-autobuild
+markdown-it-py==1.0.0
+    # via
+    #   mdit-py-plugins
+    #   myst-parser
 markupsafe==1.1.1
     # via jinja2
+mdit-py-plugins==0.2.8
+    # via myst-parser
+myst-parser==0.14.0
+    # via -r requirements/docs.in
 packaging==20.9
     # via sphinx
 pygments==2.9.0
@@ -39,8 +49,8 @@ pyparsing==2.4.7
     # via packaging
 pytz==2021.1
     # via babel
-recommonmark==0.7.1
-    # via -r requirements/docs.in
+pyyaml==5.4.1
+    # via myst-parser
 requests==2.25.1
     # via sphinx
 six==1.16.0
@@ -54,7 +64,7 @@ sphinx-rtd-theme==0.5.2
 sphinx==3.5.4
     # via
     #   -r requirements/docs.in
-    #   recommonmark
+    #   myst-parser
     #   sphinx-autobuild
     #   sphinx-rtd-theme
 sphinxcontrib-applehelp==1.0.2