From e509231d8590e0fec32f239a6c11c2653e8967bb Mon Sep 17 00:00:00 2001
From: Jordan Borean <jborean93@gmail.com>
Date: Mon, 29 Jan 2024 12:27:09 +1000
Subject: [PATCH] Use MyST for markdown docs build

Moves away from recommonmark to MyST when building the markdown docs.
Recommonmark is deprecated and no longer maintained in favour of MyST.
The only change here is to swap up the dependencies and enable the MyST
plugin in the conf.py.

Signed-off-by: Jordan Borean <jborean93@gmail.com>
---
 docs-requirements.txt                         |  2 +-
 docs/custom_extensions/custom_recommonmark.py |  8 --------
 docs/source/conf.py                           | 10 +++-------
 3 files changed, 4 insertions(+), 16 deletions(-)
 delete mode 100644 docs/custom_extensions/custom_recommonmark.py

diff --git a/docs-requirements.txt b/docs-requirements.txt
index a2223745..8a0d1c8e 100644
--- a/docs-requirements.txt
+++ b/docs-requirements.txt
@@ -1,4 +1,4 @@
+myst-parser  # For parsing markdown docs instead of rst
 Sphinx >= 1.3.1
 sphinx-autoapi
 sphinx-rtd-theme >= 0.2.5b1
-recommonmark >= 0.4.0
diff --git a/docs/custom_extensions/custom_recommonmark.py b/docs/custom_extensions/custom_recommonmark.py
deleted file mode 100644
index f7e767b6..00000000
--- a/docs/custom_extensions/custom_recommonmark.py
+++ /dev/null
@@ -1,8 +0,0 @@
-from recommonmark.parser import CommonMarkParser
-from docutils import nodes
-
-# treats "verbatim" (code without a language specified) as a code sample
-class AllCodeCommonMarkParser(CommonMarkParser):
-    def verbatim(self, text):
-        node = nodes.literal_block(text, text)
-        self.current_node.append(node)
diff --git a/docs/source/conf.py b/docs/source/conf.py
index b7a88039..8d99409a 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -20,8 +20,6 @@
 
 sys.path.insert(0, os.path.abspath('../custom_extensions'))
 
-from custom_recommonmark import AllCodeCommonMarkParser
-
 # -- General configuration -----------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -30,6 +28,7 @@
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
+  'myst_parser',
   'sphinx.ext.autodoc',
   'sphinx.ext.intersphinx',
   'sphinx.ext.viewcode',
@@ -47,14 +46,11 @@
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
-# Parsers for different suffixes
-source_parsers = {
-    '.md': AllCodeCommonMarkParser
-}
-
 # The suffix of source filenames.
 source_suffix = ['.rst', '.md']
 
+myst_all_links_external = True
+
 # The encoding of source files.
 #source_encoding = 'utf-8-sig'