Support for mkdocs material (#26)

* Support for mkdocs material superfences syntax

Add a block info parsing function that detects and parse when it uses the pymdown superfences brace format.
To use this parser, use `--markdown-docs-syntax=superfences`

Author: avandierast

README.md

@@ -136,6 +136,20 @@ assert a + " world" == "hello world"
 ```
 ````
 
+### Compatibility with Material for MkDocs
+
+Material for Mkdocs is not compatible with the default syntax.
+
+But if the extension `pymdownx.superfences` is configured for mkdocs, the brace format can be used:
+````markdown
+```{.python continuation}
+````
+
+You will need to call pytest with the `--markdown-docs-syntax` option:
+```shell
+pytest --markdown-docs --markdown-docs-syntax=superfences
+```
+
 ## MDX Comments for Metadata Options
 In .mdx files, you can use MDX comments to provide additional options for code blocks. These comments should be placed immediately before the code block and take the following form:
 
@@ -175,4 +189,4 @@ Or for fun, you can use this plugin to include testing of the validity of snippe
   * Line numbers are "wrong" for docstring-inlined snippets (since we don't know where in the file the docstring starts)
   * Line numbers are "wrong" for continuation blocks even in pure markdown files (can be worked out with some refactoring)
 * There are probably more appropriate ways to use pytest internal APIs to get more features "for free" - current state of the code is a bit "patch it til' it works".
-* Assertions are not rewritten w/ pretty data structure inspection like they are with regular pytest tests by default
+* Assertions are not rewritten w/ pretty data structure inspection like they are with regular pytest tests by default

src/pytest_markdown_docs/plugin.py

@@ -5,6 +5,7 @@
 import pathlib
 import pytest
 import typing
+from enum import Enum
 
 from _pytest._code import ExceptionInfo
 from _pytest.config.argparsing import Parser
@@ -25,6 +26,11 @@
 MARKER_NAME = "markdown-docs"
 
 
+class FenceSyntax(Enum):
+    default = "default"
+    superfences = "superfences"
+
+
 class MarkdownInlinePythonItem(pytest.Item):
     def __init__(
         self,
@@ -155,6 +161,7 @@ def reportinfo(self):
 def extract_code_blocks(
     markdown_string: str,
     markdown_type: str = "md",
+    fence_syntax: FenceSyntax = FenceSyntax.default,
 ) -> typing.Generator[typing.Tuple[str, typing.List[str], int], None, None]:
     import markdown_it
 
@@ -167,7 +174,10 @@ def extract_code_blocks(
             continue
 
         startline = block.map[0] + 1  # skip the info line when counting
-        code_info = block.info.split()
+        if fence_syntax == FenceSyntax.superfences:
+            code_info = parse_superfences_block_info(block.info)
+        else:
+            code_info = block.info.split()
 
         lang = code_info[0] if code_info else None
         code_options = set(code_info) - {lang}
@@ -200,6 +210,34 @@ def extract_code_blocks(
             prev = code_block
 
 
+def parse_superfences_block_info(block_info: str) -> typing.List[str]:
+    """Parse PyMdown Superfences block info syntax.
+
+    The default `python continuation` format is not compatible with Material for Mkdocs.
+    But, PyMdown Superfences has a special brace format to add options to code fence blocks: `{.<lang> <option1> <option2>}`.
+
+    This function also works if the default syntax is used to allow for mixed usage.
+    """
+    block_info = block_info.strip()
+
+    if not block_info.startswith("{"):
+        # default syntax
+        return block_info.split()
+
+    block_info = block_info.strip("{}")
+    code_info = block_info.split()
+    # Lang may not be the first but is always the first element that starts with a dot.
+    # (https://facelessuser.github.io/pymdown-extensions/extensions/superfences/#injecting-classes-ids-and-attributes)
+    dot_lang = next(
+        (info_part for info_part in code_info if info_part.startswith(".")), None
+    )
+    if dot_lang:
+        code_info.remove(dot_lang)
+        lang = dot_lang[1:]
+        code_info.insert(0, lang)
+    return code_info
+
+
 def is_mdx_comment(block: "Token") -> bool:
     return (
         block.type == "inline"
@@ -219,29 +257,6 @@ def extract_options_from_mdx_comment(comment: str) -> typing.Set[str]:
     return set(option.strip() for option in comment.split(" ") if option)
 
 
-def find_object_tests_recursive(
-    module_name: str, object: typing.Any
-) -> typing.Generator[
-    typing.Tuple[int, typing.Any, typing.Tuple[str, typing.List[str], int]], None, None
-]:
-    docstr = inspect.getdoc(object)
-
-    if docstr:
-        for i, code_block in enumerate(extract_code_blocks(docstr)):
-            yield i, object, code_block
-
-    for member_name, member in inspect.getmembers(object):
-        if member_name.startswith("_"):
-            continue
-
-        if (
-            inspect.isclass(member)
-            or inspect.isfunction(member)
-            or inspect.ismethod(member)
-        ) and member.__module__ == module_name:
-            yield from find_object_tests_recursive(module_name, member)
-
-
 class MarkdownDocstringCodeModule(pytest.Module):
     def collect(self):
         if pytest.version_tuple >= (8, 1, 0):
@@ -257,7 +272,7 @@ def collect(self):
             test_code,
             fixture_names,
             start_line,
-        ) in find_object_tests_recursive(module.__name__, module):
+        ) in self.find_object_tests_recursive(module.__name__, module):
             obj_name = (
                 getattr(obj, "__qualname__", None)
                 or getattr(obj, "__name__", None)
@@ -272,14 +287,44 @@ def collect(self):
                 fake_line_numbers=True,  # TODO: figure out where docstrings are in file to offset line numbers properly
             )
 
+    def find_object_tests_recursive(
+        self, module_name: str, object: typing.Any
+    ) -> typing.Generator[
+        typing.Tuple[int, typing.Any, typing.Tuple[str, typing.List[str], int]],
+        None,
+        None,
+    ]:
+        docstr = inspect.getdoc(object)
+
+        if docstr:
+            fence_syntax = FenceSyntax(self.config.option.markdowndocs_syntax)
+            for i, code_block in enumerate(
+                extract_code_blocks(docstr, fence_syntax=fence_syntax)
+            ):
+                yield i, object, code_block
+
+        for member_name, member in inspect.getmembers(object):
+            if member_name.startswith("_"):
+                continue
+
+            if (
+                inspect.isclass(member)
+                or inspect.isfunction(member)
+                or inspect.ismethod(member)
+            ) and member.__module__ == module_name:
+                yield from self.find_object_tests_recursive(module_name, member)
+
 
 class MarkdownTextFile(pytest.File):
     def collect(self):
         markdown_content = self.path.read_text("utf8")
+        fence_syntax = FenceSyntax(self.config.option.markdowndocs_syntax)
 
         for i, (code_block, fixture_names, start_line) in enumerate(
             extract_code_blocks(
-                markdown_content, markdown_type=self.path.suffix.replace(".", "")
+                markdown_content,
+                markdown_type=self.path.suffix.replace(".", ""),
+                fence_syntax=fence_syntax,
             )
         ):
             yield MarkdownInlinePythonItem.from_parent(
@@ -321,6 +366,14 @@ def pytest_addoption(parser: Parser) -> None:
         help="run ",
         dest="markdowndocs",
     )
+    group.addoption(
+        "--markdown-docs-syntax",
+        action="store",
+        choices=[choice.value for choice in FenceSyntax],
+        default="default",
+        help="Choose an alternative fences syntax",
+        dest="markdowndocs_syntax",
+    )
 
 
 def pytest_addhooks(pluginmanager):

tests/plugin_test.py

@@ -350,3 +350,44 @@ def test_notest_mdx_comment(testdir):
     )
     result = testdir.runpytest("--markdown-docs")
     result.assert_outcomes(passed=0)
+
+
+def test_superfences_format_markdown(testdir):
+    testdir.makefile(
+        ".md",
+        """
+        ```python
+        b = "hello"
+        ```
+
+        ```{.python continuation}
+        assert b + " world" == "hello world"
+        ```
+
+        # the lang may not be the first element
+        ```{other_option .python .other-class continuation}
+        assert b + " world" == "hello world"
+        ```
+    """,
+    )
+    result = testdir.runpytest("--markdown-docs", "--markdown-docs-syntax=superfences")
+    result.assert_outcomes(passed=3)
+
+
+def test_superfences_format_docstring(testdir):
+    testdir.makepyfile(
+        """
+        def simple():
+            \"\"\"
+            ```python
+            b = "hello"
+            ```
+
+            ```{.python continuation}
+            assert b + " world" == "hello world"
+            ```
+            \"\"\"
+        """
+    )
+    result = testdir.runpytest("--markdown-docs", "--markdown-docs-syntax=superfences")
+    result.assert_outcomes(passed=2)