Update documentation toolchain

DOCS.md

@@ -1,9 +1,10 @@
 # Coconut Documentation
 
-```eval_rst
-.. contents::
-    :local:
-    :depth: 2
+```{contents}
+---
+local:
+depth: 2
+---
 ```
 
 ## Overview

FAQ.md

@@ -2,9 +2,10 @@
 
 ## Frequently Asked Questions
 
-```eval_rst
-.. contents::
-    :local:
+```{contents}
+---
+local:
+---
 ```
 
 ### Can I use Python modules from Coconut and Coconut modules from Python?

HELP.md

@@ -1,8 +1,9 @@
 # Coconut Tutorial
 
-```eval_rst
-.. contents::
-    :local:
+```{contents}
+---
+local:
+---
 ```
 
 ## Introduction

coconut/constants.py

@@ -555,7 +555,7 @@ def str_to_bool(boolstr, default=False):
     "docs": (
         "sphinx",
         "pygments",
-        "recommonmark",
+        "myst-parser",
         "sphinx_bootstrap_theme",
     ),
     "tests": (
@@ -571,7 +571,6 @@ def str_to_bool(boolstr, default=False):
 min_versions = {
     "cPyparsing": (2, 4, 7, 1, 0, 0),
     ("pre-commit", "py3"): (2,),
-    "recommonmark": (0, 7),
     "psutil": (5,),
     "jupyter": (1, 0),
     "mypy[python2]": (0, 910),
@@ -586,6 +585,9 @@ def str_to_bool(boolstr, default=False):
     ("numpy", "py2;cpy"): (1,),
     ("dataclasses", "py36-only"): (0, 8),
     ("aenum", "py<34"): (3,),
+    "sphinx": (4, 2),
+    "sphinx_bootstrap_theme": (0, 8),
+    "myst-parser": (0, 15),
     # don't upgrade this until https://github.com/jupyter/jupyter_console/issues/241 is fixed
     ("jupyter-client", "py3"): (6, 1),
     # latest version supported on Python 2
@@ -611,9 +613,6 @@ def str_to_bool(boolstr, default=False):
     ("ipykernel", "py2"): (4, 10),
     ("prompt_toolkit", "mark2"): (1,),
     "watchdog": (0, 10),
-    # don't upgrade these; they break on master
-    "sphinx": (1, 7, 4),
-    "sphinx_bootstrap_theme": (0, 4, 8),
     # don't upgrade this; it breaks with old IPython versions
     "jedi": (0, 17),
     # Coconut works best on pyparsing 2
@@ -639,8 +638,6 @@ def str_to_bool(boolstr, default=False):
     ("ipykernel", "py2"),
     ("prompt_toolkit", "mark2"),
     "watchdog",
-    "sphinx",
-    "sphinx_bootstrap_theme",
     "jedi",
     "pyparsing",
 )
@@ -652,8 +649,6 @@ def str_to_bool(boolstr, default=False):
 max_versions = {
     "pyparsing": _,
     "cPyparsing": (_, _, _),
-    "sphinx": _,
-    "sphinx_bootstrap_theme": (_, _),
     "mypy[python2]": _,
     ("prompt_toolkit", "mark2"): _,
     "jedi": _,

conf.py

@@ -30,9 +30,8 @@
 )
 from coconut.util import univ_open
 
+import myst_parser  # NOQA
 from sphinx_bootstrap_theme import get_html_theme_path
-from recommonmark.parser import CommonMarkParser
-from recommonmark.transform import AutoStructify
 
 # -----------------------------------------------------------------------------------------------------------------------
 # README:
@@ -68,42 +67,13 @@
 exclude_patterns = ["README.*"]
 
 source_suffix = [".rst", ".md"]
-source_parsers = {
-    ".md": CommonMarkParser,
-}
 
 default_role = "code"
 
-# -----------------------------------------------------------------------------------------------------------------------
-# SETUP:
-# -----------------------------------------------------------------------------------------------------------------------
+extensions = ["myst_parser"]
 
+myst_enable_extensions = [
+    "smartquotes",
+]
 
-class PatchedAutoStructify(AutoStructify, object):
-    """AutoStructify by default can't handle contents directives."""
-
-    def patched_nested_parse(self, *args, **kwargs):
-        """Sets match_titles then calls stored_nested_parse."""
-        kwargs["match_titles"] = True
-        return self.stored_nested_parse(*args, **kwargs)
-
-    def auto_code_block(self, *args, **kwargs):
-        """Modified auto_code_block that patches nested_parse."""
-        self.stored_nested_parse = self.state_machine.state.nested_parse
-        self.state_machine.state.nested_parse = self.patched_nested_parse
-        try:
-            return super(PatchedAutoStructify, self).auto_code_block(*args, **kwargs)
-        finally:
-            self.state_machine.state.nested_parse = self.stored_nested_parse
-
-
-def setup(app):
-    app.add_config_value(
-        "recommonmark_config", {
-            "enable_auto_toc_tree": False,
-            "enable_inline_math": False,
-            "enable_auto_doc_ref": False,
-        },
-        True,
-    )
-    app.add_transform(PatchedAutoStructify)
+myst_heading_anchors = 4