build(docs): add support for Markdown documentation

This changes adds support for building Markdown documentation into
Sphinx with [MyST]. We'll make use of this in a later patch, where we
introduce automatically-generated Markdown documentation that needs to
be compiled as part of the Sphinx documentation.

[MyST]: https://myst-parser.readthedocs.io/en/latest

Change-Id: I2a241a588c579fac1a81e1853479908928be1fc8
Signed-off-by: Chris Kay <chris.kay@arm.com>

docs/conf.py

@@ -20,13 +20,13 @@ project = 'Trusted Firmware-A'
 # 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.autosectionlabel', 'sphinxcontrib.plantuml']
+extensions = ['myst_parser', 'sphinx.ext.autosectionlabel', 'sphinxcontrib.plantuml']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
 # The suffix(es) of source filenames.
-source_suffix = '.rst'
+source_suffix = ['.md', '.rst']
 
 # The master toctree document.
 master_doc = 'index'

docs/requirements.in

@@ -1,3 +1,4 @@
+myst-parser==0.15.2
 pip-tools==6.4.0
 sphinx==4.2.0
 sphinx-rtd-theme==1.0.0

docs/requirements.txt

@@ -6,6 +6,8 @@
 #
 alabaster==0.7.12
     # via sphinx
+attrs==21.2.0
+    # via markdown-it-py
 babel==2.9.1
     # via sphinx
 certifi==2021.5.30
@@ -16,6 +18,7 @@ click==8.0.1
     # via pip-tools
 docutils==0.16
     # via
+    #   myst-parser
     #   sphinx
     #   sphinx-rtd-theme
 idna==3.2
@@ -23,9 +26,19 @@ idna==3.2
 imagesize==1.2.0
     # via sphinx
 jinja2==3.0.1
-    # via sphinx
+    # via
+    #   myst-parser
+    #   sphinx
+markdown-it-py==1.1.0
+    # via
+    #   mdit-py-plugins
+    #   myst-parser
 markupsafe==2.0.1
     # via jinja2
+mdit-py-plugins==0.2.8
+    # via myst-parser
+myst-parser==0.15.2
+    # via -r requirements.in
 packaging==21.0
     # via sphinx
 pep517==0.11.0
@@ -38,6 +51,8 @@ pyparsing==2.4.7
     # via packaging
 pytz==2021.1
     # via babel
+pyyaml==6.0
+    # via myst-parser
 requests==2.26.0
     # via sphinx
 snowballstemmer==2.1.0
@@ -45,6 +60,7 @@ snowballstemmer==2.1.0
 sphinx==4.2.0
     # via
     #   -r requirements.in
+    #   myst-parser
     #   sphinx-rtd-theme
     #   sphinxcontrib-plantuml
 sphinx-rtd-theme==1.0.0