docs: Configure Sphinx, MyST, enable extensions

Configure Sphinx extensions, configure MyST, enable some extensions,
to simplify creating beautiful-looking documentation.

Signed-off-by: Vangelis Koukis <[email protected]>

docs/conf.py

@@ -13,7 +13,8 @@
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = ["myst_parser", "sphinx_copybutton", "sphinx.ext.githubpages"]
+extensions = ["myst_parser", "sphinx_copybutton", "sphinx_togglebutton",
+              "sphinx.ext.githubpages"]
 
 templates_path = ["templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
@@ -32,3 +33,20 @@
     "logo_height": 100,
     "show_colorset_choices": True
 }
+
+# Enable MyST parser extensions based on
+# https://myst-parser.readthedocs.io/en/stable/syntax/optional.html
+myst_enable_extensions = [ "amsmath", "attrs_inline", "colon_fence", "deflist",
+                           "dollarmath", "fieldlist", "html_admonition",
+                           "html_image", "replacements",
+                           "smartquotes", "strikethrough", "substitution",
+                           "tasklist"]
+
+# Have all external links open in a new window, so the reader doesn't lose
+# track of our instructions. See
+# https://github.com/executablebooks/MyST-Parser/issues/856
+myst_links_external_new_tab = True
+
+# Support parsing $$ even in inline contexts, i.e., inside a paragraph. See
+# https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#dollar-delimited-math
+myst_dmath_double_inline = True

requirements.txt

@@ -2,3 +2,4 @@ sphinx
 sphinx-nefertiti
 myst-parser
 sphinx-copybutton
+sphinx-togglebutton