update

chrisjsewell · chrisjsewell · commit 0676b68fe8cb · 2022-05-12T13:33:58.000+02:00
diff --git a/docs/_static/custom.css b/docs/_static/custom.css
@@ -14,3 +14,11 @@ h3::before {
     counter-increment: subsubsection;
     content: counter(subsection) "." counter(subsubsection) ". ";
 }
+
+/** No icon for admonitions with no-icon class */
+.admonition > .admonition-title, div.admonition.no-icon > .admonition-title::before {
+    content: "";
+}
+.admonition > .admonition-title, div.admonition.no-icon > .admonition-title {
+    padding-left: .6rem;
+}
diff --git a/docs/conf.py b/docs/conf.py
@@ -156,8 +156,13 @@
 
 def setup(app: Sphinx):
     """Add functions to the Sphinx setup."""
-    from myst_parser._docs import DocutilsCliHelpDirective, MystConfigDirective
+    from myst_parser._docs import (
+        DirectiveDoc,
+        DocutilsCliHelpDirective,
+        MystConfigDirective,
+    )
 
     app.add_css_file("custom.css")
     app.add_directive("myst-config", MystConfigDirective)
     app.add_directive("docutils-cli-help", DocutilsCliHelpDirective)
+    app.add_directive("doc-directive", DirectiveDoc)
diff --git a/docs/syntax/roles-and-directives.md b/docs/syntax/roles-and-directives.md
@@ -2,10 +2,10 @@
 
 # Roles and Directives
 
-Roles and directives provide a way to extend the syntax of MyST,
+Roles and directives provide a way to extend the syntax of MyST in an unbound manner,
 by interpreting a chuck of text as a specific type of markup, according to its name.
 
-Any [docutils role](https://docutils.sourceforge.io/docs/ref/rst/roles.html), [docutils directive](https://docutils.sourceforge.io/docs/ref/rst/directives.html), [sphinx role](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html), or [sphinx directive](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html) can be used in MyST.
+Mostly all [docutils roles](https://docutils.sourceforge.io/docs/ref/rst/roles.html), [docutils directives](https://docutils.sourceforge.io/docs/ref/rst/directives.html), [sphinx roles](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html), or [sphinx directives](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html) can be used in MyST.
 
 ## Syntax
 
@@ -334,7 +334,65 @@ How roles parse this content depends on the author that created the role.
 
 ## Common roles and directives
 
-Under construction...
+:::{admonition} {material-regular}`engineering;1.5rem;sd-mr-1` Currently Under Construction
+:class: no-icon
+Check back for more...
+:::
+
+### ToC Trees
+
+```{doc-directive} contents
+Insert a table of contents tree of the documents headings.
+```
+
+```{doc-directive} toctree
+Inserts a Sphinx "Table of Contents" tree, containing a list of (relative) child document paths.
+```
+
+### Admonitions
+
+```{doc-directive} admonition
+Create a generic "callout" box, containing the content.
+```
+
+```{doc-directive} note
+Create a "callout" box, specific to notes, containing the content.
+```
+
+Other admonitions (same structure as `note`): `attention`, `caution`, `danger`, `error`, `hint`, `important`, `tip`, `warning`.
+
+Sphinx only: `deprecated`, `versionadded`, `versionchanged`.
+
+### Images and Figures
+
+```{doc-directive} image
+Insert an image, from a (relative) path or URL.
+```
+
+```{doc-directive} figure
+Insert an image, from a (relative) path or URL,
+with a caption (first paragraph), and optional legend (subsequent content).
+```
+
+```{doc-directive} table
+Insert a (MyST) table with a caption.
+```
+
+### Tables
+
+```{doc-directive} list-table
+Create a table from data in a uniform two-level bullet list.
+```
+
+```{doc-directive} csv-table
+Create a table from CSV (comma-separated values) data.
+```
+
+### Code
+
+```{doc-directive} code-block
+Syntax highlight a block of code, according to the language.
+```
 
 (syntax/roles/special)=
 
diff --git a/docs/syntax/syntax.md b/docs/syntax/syntax.md
@@ -7,7 +7,8 @@
 MyST is a strict superset of the [CommonMark syntax specification](https://spec.commonmark.org/).
 It adds features focussed on scientific and technical documentation authoring, as detailed below.
 
-In addition, the roles and directives syntax provide inline/block-level extension points for plugins. This is detailed further in the [Roles and Directives](roles-directives) section.
+In addition, the roles and directives syntax provide inline/block-level extension points for plugins.
+This is detailed further in the [Roles and Directives](roles-directives) section.
 
 :::{seealso}
 The [syntax token reference tables](syntax-tokens)
@@ -37,7 +38,6 @@ Ordered List    | `1. item`
 Unordered List  | `- item`
 Code Fence      | opening ```` ```lang ```` to closing ```` ``` ````
 
-
 (syntax/frontmatter)=
 
 ## Front Matter
diff --git a/myst_parser/_docs.py b/myst_parser/_docs.py
@@ -1,14 +1,21 @@
 """Code to use internally, for documentation."""
 from __future__ import annotations
 
+import io
 from typing import Sequence, Union
 
 from docutils import nodes
+from docutils.frontend import OptionParser
 from docutils.parsers.rst import directives
+from sphinx.directives import other
+from sphinx.util import logging
 from sphinx.util.docutils import SphinxDirective
 from typing_extensions import get_args, get_origin
 
 from .config.main import MdParserConfig
+from .parsers.docutils_ import Parser as DocutilsParser
+
+logger = logging.getLogger(__name__)
 
 
 class _ConfigBase(SphinxDirective):
@@ -117,16 +124,75 @@ class DocutilsCliHelpDirective(SphinxDirective):
 
     def run(self):
         """Run the directive."""
-        import io
-
-        from docutils import nodes
-        from docutils.frontend import OptionParser
-
-        from myst_parser.parsers.docutils_ import Parser as DocutilsParser
-
         stream = io.StringIO()
         OptionParser(
             components=(DocutilsParser,),
             usage="myst-docutils-<writer> [options] [<source> [<destination>]]",
         ).print_help(stream)
         return [nodes.literal_block("", stream.getvalue())]
+
+
+class DirectiveDoc(SphinxDirective):
+    """Load and document a directive."""
+
+    required_arguments = 1  # name of the directive
+    has_content = True
+
+    def run(self):
+        """Run the directive."""
+        name = self.arguments[0]
+        # load the directive class
+        klass, _ = directives.directive(
+            name, self.state.memo.language, self.state.document
+        )
+        if klass is None:
+            logger.warning(f"Directive {name} not found.", line=self.lineno)
+            return []
+        content = " ".join(self.content)
+        text = f"""\
+:Name: `{name}`
+:Description: {content}
+:Arguments: {klass.required_arguments} required, {klass.optional_arguments} optional
+:Content: {'yes' if klass.has_content else 'no'}
+:Options:
+"""
+        if klass.option_spec:
+            text += "  name | type\n  -----|------\n"
+            for key, func in klass.option_spec.items():
+                text += f"  {key} | {convert_opt(name, func)}\n"
+        node = nodes.Element()
+        self.state.nested_parse(text.splitlines(), 0, node)
+        return node.children
+
+
+def convert_opt(name, func):
+    """Convert an option function to a string."""
+    if func is directives.flag:
+        return "flag"
+    if func is directives.unchanged:
+        return "text"
+    if func is directives.unchanged_required:
+        return "text"
+    if func is directives.class_option:
+        return "space-delimited list"
+    if func is directives.uri:
+        return "URI"
+    if func is directives.path:
+        return "path"
+    if func is int:
+        return "integer"
+    if func is directives.positive_int:
+        return "integer (positive)"
+    if func is directives.nonnegative_int:
+        return "integer (non-negative)"
+    if func is directives.positive_int_list:
+        return "space/comma-delimited list of integers (positive)"
+    if func is directives.percentage:
+        return "percentage"
+    if func is directives.length_or_unitless:
+        return "length or unitless"
+    if func is directives.length_or_percentage_or_unitless:
+        return "length, percentage or unitless"
+    if func is other.int_or_nothing:
+        return "integer"
+    return ""
