Update API documentation (#111)

docs/api/directive.rst

@@ -0,0 +1,7 @@
+.. _api/directive:
+
+Directive Parsing
+-----------------
+
+.. automodule:: myst_parser.parse_directives
+    :members:

docs/api/index.md

@@ -6,6 +6,7 @@
 :maxdepth: 2
 
 tokens.rst
+directive.rst
 renderers.rst
 sphinx_parser.rst
 ```

docs/api/renderers.rst

@@ -12,25 +12,31 @@ HTML
 ....
 
 .. autoclass:: myst_parser.html_renderer.HTMLRenderer
-    :members:
+    :special-members: __init__, __enter__, __exit__
+    :members: default_block_tokens, default_span_tokens
     :undoc-members:
+    :member-order: alphabetical
     :show-inheritance:
 
 
 JSON
 ....
 
 .. autoclass:: myst_parser.json_renderer.JsonRenderer
-    :members:
+    :special-members: __init__, __enter__, __exit__
+    :members: default_block_tokens, default_span_tokens
     :undoc-members:
+    :member-order: alphabetical
     :show-inheritance:
 
 Docutils
 ........
 
 .. autoclass:: myst_parser.docutils_renderer.DocutilsRenderer
-    :members:
+    :special-members: __init__, __enter__, __exit__
+    :members: default_block_tokens, default_span_tokens, new_document
     :undoc-members:
+    :member-order: alphabetical
     :show-inheritance:
 
 
@@ -58,6 +64,10 @@ Sphinx
 ......
 
 .. autoclass:: myst_parser.docutils_renderer.SphinxRenderer
-    :members:
+    :special-members: __init__, __enter__, __exit__
+    :members: default_block_tokens, default_span_tokens, mock_sphinx_env
     :undoc-members:
+    :member-order: alphabetical
     :show-inheritance:
+
+.. autofunction:: myst_parser.docutils_renderer.dict_to_docinfo

docs/api/tokens.rst

@@ -3,10 +3,12 @@
 Extended AST Tokens
 -------------------
 
-MyST builds on the mistletoe
-:ref:`core block tokens <mistletoe:tokens/block>` and
-:ref:`core span tokens <mistletoe:tokens/span>`
-to extend the syntax (as discussed in :ref:`example_syntax`).
+MyST builds on the mistletoe tokens, to extend the syntax:
+
+- :ref:`Core block tokens <mistletoe:tokens/block>`
+- :ref:`Core span tokens <mistletoe:tokens/span>`
+- :ref:`Extension tokens <mistletoe:tokens/extension>`
+
 
 .. seealso::
 

docs/conf.py

@@ -99,14 +99,14 @@ def run_apidoc(app):
     "sphinx": ("https://www.sphinx-doc.org/en/master", None),
 }
 
-autodoc_default_options = {
-    "show-inheritance": True,
-    "special-members": "__init__, __enter__, __exit__",
-    "members": True,
-    # 'exclude-members': '',
-    "undoc-members": True,
-    # 'inherited-members': True
-}
+# autodoc_default_options = {
+#     "show-inheritance": True,
+#     "special-members": "__init__, __enter__, __exit__",
+#     "members": True,
+#     # 'exclude-members': '',
+#     "undoc-members": True,
+#     # 'inherited-members': True
+# }
 autodoc_member_order = "bysource"
 
 nitpick_ignore = [

myst_parser/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.5.0a1"
+__version__ = "0.5.0"
 
 
 def text_to_tokens(text: str):

myst_parser/docutils_renderer.py

@@ -91,6 +91,7 @@ def __init__(
         super().__init__(find_blocks=find_blocks, find_spans=find_spans)
 
     def new_document(self, source_path="notset") -> nodes.document:
+        """Create a new docutils document."""
         settings = OptionParser(components=(RSTParser,)).get_default_values()
         return new_document(source_path, settings=settings)
 
@@ -634,7 +635,9 @@ def handle_cross_reference(self, token, destination):
             self.render_children(token)
 
     def mock_sphinx_env(self, configuration=None, sourcedir=None):
-        """Load sphinx roles, directives, etc."""
+        """Create a minimimal Sphinx environment;
+        loading sphinx roles, directives, etc.
+        """
         from sphinx.application import builtin_extensions, Sphinx
         from sphinx.config import Config
         from sphinx.environment import BuildEnvironment

myst_parser/parse_directives.py

@@ -1,10 +1,9 @@
-"""Module to parse fenced code blocks as directives.
-
-Such a fenced code block starts with `{directive_name}`,
+"""Fenced code blocks are parsed as directives,
+if the block starts with ``{directive_name}``,
 followed by arguments on the same line.
 
 Directive options are read from a YAML block,
-if the first content line starts with `---`, e.g.
+if the first content line starts with ``---``, e.g.
 
 ::
 
@@ -17,8 +16,8 @@
     content...
     ```
 
-Or the option block will be parsed if the first content line starts with `:`,
-as a YAML block consisting of every line that starts with a `:`, e.g.
+Or the option block will be parsed if the first content line starts with ``:``,
+as a YAML block consisting of every line that starts with a ``:``, e.g.
 
 ::
 
@@ -45,13 +44,15 @@
 
 
 class DirectiveParsingError(Exception):
+    """Raise on parsing/validation error."""
+
     pass
 
 
 def parse_directive_text(
     directive_class: Type[Directive], argument_str: str, content: str
 ):
-    """See module docstring."""
+    """Parse (and validate) the full directive text."""
     if directive_class.option_spec:
         body, options = parse_directive_options(content, directive_class)
     else:
@@ -87,6 +88,7 @@ def parse_directive_text(
 
 
 def parse_directive_options(content: str, directive_class: Type[Directive]):
+    """Parse (and validate) the directive option section."""
     options = {}
     if content.startswith("---"):
         content = "\n".join(content.splitlines()[1:])
@@ -141,6 +143,7 @@ def parse_directive_options(content: str, directive_class: Type[Directive]):
 
 
 def parse_directive_arguments(directive, arg_text):
+    """Parse (and validate) the directive argument section."""
     required = directive.required_arguments
     optional = directive.optional_arguments
     arguments = arg_text.split()

setup.py

@@ -36,7 +36,7 @@
     ],
     keywords="markdown lexer parser development docutils sphinx",
     python_requires=">=3.6",
-    install_requires=["mistletoe-ebp==0.9.4a2"],
+    install_requires=["mistletoe-ebp~=0.9.4"],
     extras_require={
         "sphinx": ["pyyaml", "docutils>=0.15", "sphinx>=2,<3"],
         "code_style": ["flake8<3.8.0,>=3.7.0", "black", "pre-commit==1.17.0"],

tests/test_syntax/test_ast.py

@@ -74,35 +74,6 @@ def test_role(name, json_renderer, data_regression, strings):
     data_regression.check(json_renderer.render(document, as_string=False))
 
 
-@pytest.mark.parametrize(
-    "name,strings",
-    [
-        ("basic", ["$a$"]),
-        ("contains_special_chars", ["$a`{_*-%$"]),
-        ("preceding_special_chars", ["{_*-%`$a$"]),
-        ("multiple", ["$a$ $b$"]),
-        ("escaped_opening", ["\\$a $b$"]),
-        ("no_closing", ["$a"]),
-        ("internal_emphasis", ["$*a*$"]),
-        ("external_emphasis", ["*$a$*"]),
-        ("multiline", ["$$a", "c", "b$$"]),
-        (
-            "issue_51",
-            [
-                "Math can be called in-line with single `$` characters around math.",
-                "For example, `$x_{hey}=it+is^{math}$` renders $x_{hey}=it+is^{math}$.",
-            ],
-        ),
-        ("in_link_content", ["[$a$](link)"]),
-        ("in_link_target", ["[a]($b$)"]),
-        ("in_image", ["![$a$]($b$)"]),
-    ],
-)
-def test_math(name, json_renderer, data_regression, strings):
-    document = Document.read(strings)
-    data_regression.check(json_renderer.render(document, as_string=False))
-
-
 @pytest.mark.parametrize(
     "name,strings",
     [