🔀 MERGE: Improve optional syntaxes (#273)

Plugins are now split off into `mdit_py_plugins` and more plugins are added:

`myst_enable_extensions=["colon_fence"]` replaces `myst_admonition_enable` and `myst_figure_enable` (which are deprecated) to work exactly like standard back-tick code fences and directives, i.e. you can now use any directive as:

```
:::{name} argument
:option: value

body
:::
```

`myst_enable_extensions = ["dollarmath", ...]` now replaces and deprecates individual enable configuration variables: `admonition_enable`, `figure_enable`, `dmath_enable`, `amsmath_enable`, `deflist_enable`, `html_img_enable`

`myst_enable_extensions=["linkify", "substitution"]` are also big additions

.github/workflows/tests.yml

@@ -47,7 +47,7 @@ jobs:
       run: |
         python -m pip install --upgrade pip
         pip install "sphinx${{ matrix.sphinx }}"
-        pip install -e .[testing]
+        pip install -e .[linkify,testing]
     - name: Run pytest
       run: pytest
 
@@ -66,7 +66,7 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install -e .[testing]
+        pip install -e .[linkify,testing]
 
     - name: Run pytest
       run: |
@@ -94,7 +94,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -e .[rtd]
+          pip install -e .[linkify,rtd]
 
       # Build the docs
       - name: Build docs to store

.readthedocs.yml

@@ -6,7 +6,7 @@ python:
       - method: pip
         path: .
         extra_requirements:
-          - sphinx
+          - linkify
           - rtd
 
 sphinx:

docs/conf.py

@@ -34,7 +34,6 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.viewcode",
     "sphinxcontrib.bibtex",
-    "sphinx_tabs.tabs",
     "sphinx_panels",
 ]
 
@@ -65,15 +64,20 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
 
-myst_amsmath_enable = True
-myst_admonition_enable = True
-myst_html_img_enable = True
-myst_dmath_enable = True
-myst_deflist_enable = True
-myst_figure_enable = True
+myst_enable_extensions = [
+    "dollarmath",
+    "amsmath",
+    "deflist",
+    "html_image",
+    "colon_fence",
+    "smartquotes",
+    "replacements",
+    "linkify",
+    "substitution",
+]
 myst_url_schemes = ("http", "https", "mailto")
 myst_heading_anchors = 2
-panels_add_boostrap_css = False
+panels_add_bootstrap_css = False
 
 
 def run_apidoc(app):

docs/examples/index.md

@@ -19,17 +19,14 @@ wealth_dynamics_md.md
 The following tabs show the raw content of each of the above documents, for quick
 comparison.
 
-`````{tabs}
-````{tab} MyST Markdown
-
+````{tabbed} MyST Markdown
 Raw source for {doc}`wealth_dynamics_md`
 ```{literalinclude} wealth_dynamics_md.md
 ```
 ````
-````{tab} reStructuredText
 
+````{tabbed} reStructuredText
 Raw source for {doc}`wealth_dynamics_rst`
 ```{literalinclude} wealth_dynamics_rst.rst
 ```
 ````
-`````

docs/using/intro.md

@@ -41,7 +41,8 @@ To use the MyST parser in Sphinx, simply add: `extensions = ["myst_parser"]` to
 
 Naturally this site is generated with Sphinx and MyST!
 
-:::{admonition,tip} You can use both MyST and reStructuredText
+:::{admonition} You can use both MyST and reStructuredText
+:class: tip
 
 Activating the MyST parser will simply *enable* parsing markdown files with MyST, and the rST parser that ships with Sphinx by default will still work the same way.
 You can have combinations of both markdown and rST files in your documentation, and Sphinx will choose the right parser based on each file's extension.
@@ -50,7 +51,8 @@ Sphinx features like cross-references will work just fine between the pages.
 You can even inject raw rST into Markdown files! (see [this explanation](syntax/directives/parsing))
 :::
 
-:::{admonition,seealso} Want to add Jupyter Notebooks to your documentation?
+:::{admonition} Want to add Jupyter Notebooks to your documentation?
+:class: seealso
 
 See also [MyST-NB](https://myst-nb.readthedocs.io), our complimentary parser and execution engine,
 for ipynb and text-based notebooks.
@@ -234,32 +236,38 @@ To do so, use the keywords beginning `myst_`.
 * - `myst_disable_syntax`
   - ()
   - List of markdown syntax elements to disable, see the [markdown-it parser guide](markdown_it:using).
+* - `enable_extensions`
+  - `["dollarmath"]`
+  - Enable Markdown extensions, [see here](syntax-optional) for details.
 * - `myst_url_schemes`
   - `None`
   - [URI schemes](https://en.wikipedia.org/wiki/List_of_URI_schemes) that will be recognised as external URLs in `[](scheme:loc)` syntax, or set `None` to recognise all.
     Other links will be resolved as internal cross-references.
-* - `myst_html_img_enable`
-  - `False`
-  - Convert HTML `<img>` elements to sphinx image nodes, see the [image syntax](syntax/images) for details
-* - `myst_admonition_enable`
-  - `False`
-  - Enable admonition style directives, [see here](syntax/admonitions) for details.
 * - `myst_heading_anchors`
   - `None`
   - Enable auto-generated heading anchors, up to a maximum level, [see here](syntax/header-anchors) for details.
 `````
 
-Math specific, see the [Math syntax](syntax/math) for more details:
+List of extensions:
+
+- "amsmath": enable direct parsing of [amsmath](https://ctan.org/pkg/amsmath) LaTeX equations
+- "colon_fence": Enable code fences using `:::` delimiters, [see here](syntax/colon_fence) for details
+- "deflist"
+- "dollarmath": Enable parsing of dollar `$` and `$$` encapsulated math
+- "html_image": Convert HTML `<img>` elements to sphinx image nodes, see the [image syntax](syntax/images) for details
+- "linkify": automatically identify "bare" web URLs and add hyperlinks
+- "replacements": automatically convert some common typographic texts
+- "smartquotes": automatically convert standard quotations to their opening/closing variants
+- "substitution": substitute keys
+
+Math specific, when `"dollarmath"` activated, see the [Math syntax](syntax/math) for more details:
 
 `````{list-table}
 :header-rows: 1
 
 * - Option
   - Default
   - Description
-* - `myst_dmath_enable`
-  - `True`
-  - Enable parsing of dollar `$` and `$$` encapsulated math
 * - `myst_dmath_allow_labels`
   - `True`
   - Parse `$$...$$ (label)` syntax (if dmath enabled)