Infra/snapshot testing + mkdocstring support in qmd

.pre-commit-config.yaml

@@ -1,25 +1,25 @@
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.6.0
+    rev: v6.0.0
     hooks:
       - id: check-yaml
         exclude: "mkdocs.yml"
       - id: end-of-file-fixer
         exclude: "(.*tests/data/.*/.*.md)"
       - id: trailing-whitespace
-        exclude: "(.*tests/data/.*/.*.md)"
+        exclude: "(.*tests/data/.*/.*.md)|(tests/__snapshots__/.*.ambr)"
       - id: debug-statements
   - repo: https://github.com/PyCQA/autoflake
     rev: v2.3.1
     hooks:
       - id: autoflake
   - repo: https://github.com/psf/black
-    rev: 24.8.0
+    rev: 25.11.0
     hooks:
       - id: black
         language_version: python3.11
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: v0.6.3
+    rev: v0.14.4
     hooks:
       - id: ruff
   - repo: local

docs/examples/example.md

@@ -253,12 +253,12 @@ raise NotImplementedError
 ```
 
 ::: {.cell-output .cell-output-error}
-    NotImplementedError: 
+    NotImplementedError:
     ---------------------------------------------------------------------------
     NotImplementedError                       Traceback (most recent call last)
     Cell In[24], line 1
     ----> 1 raise NotImplementedError
 
-    NotImplementedError: 
+    NotImplementedError:
 :::
 ::::

docs/examples/matplotlib_example.qmd

@@ -34,4 +34,4 @@ ax.set(xticklabels=[],
        zticklabels=[])
 
 plt.show()
-```
+```

docs/examples/mermaid_example.qmd

@@ -7,4 +7,4 @@ graph TD;
     A-->C;
     B-->D;
     C-->D;
-```
+```

docs/examples/mkdocstrings_example.qmd

@@ -0,0 +1,18 @@
+
+# This is a simple example that uses mkdocstrings
+
+You can take a look at the .qmd that generated this docs
+from:
+
+[https://github.com/jspaezp/mkquartodocs/tree/main/docs](https://github.com/jspaezp/mkquartodocs/tree/main/docs)
+
+## Docs for math.sqrt
+
+::: math.sqrt
+
+```{python}
+import math
+
+print(f"The quare root of 16 is {math.sqrt(16)}")
+
+```

docs/javascripts/tablesort.js

@@ -3,4 +3,4 @@ document$.subscribe(function() {
     tables.forEach(function(table) {
       new Tablesort(table)
     })
-  })
+  })

mkdocs.yml

@@ -13,21 +13,24 @@ nav:
     - 'Simple dataframe execution': 'examples/dataframe_example.qmd'
     - 'Simple mermaid execution': 'examples/mermaid_example.qmd'
     - 'Simple matplotlib execution': 'examples/matplotlib_example.qmd'
+    - 'Mkdocstrings Integration': 'examples/mkdocstrings_example.qmd'
 
 theme:
   name: material
 
 plugins:
-  - search
-  - mkquartodocs:
-      # keep_output: true
-      force_rebuild: true
+- mkdocstrings:
+    default_handler: python
+- search
+- mkquartodocs:
+    # keep_output: true
+    force_rebuild: true
 
 markdown_extensions:
-  - pymdownx.highlight:
-      anchor_linenums: true
-  - pymdownx.superfences
+- pymdownx.highlight:
+    anchor_linenums: true
+- pymdownx.superfences
 
 extra_javascript:
-  - https://unpkg.com/[email protected]/dist/tablesort.min.js
-  - javascripts/tablesort.js
+- https://unpkg.com/[email protected]/dist/tablesort.min.js
+- javascripts/tablesort.js

mkquartodocs/extension.py

@@ -39,6 +39,18 @@
 # ``` {.python .cell-code}
 CODEBLOCK_REGEX: Final = re.compile(r"^(`{3,})\s?{\.(\w+) .*}")
 
+# mkdocstrings syntax normalization:
+# Quarto wraps markdown divs (including mkdocstrings `::: module.path` syntax)
+# in extra colons when rendering nested structures. For example:
+#   Source .qmd: `::: pathlib.Path`
+#   Quarto output: `::::: pathlib.Path` (5 colons instead of 3)
+# mkdocstrings expects exactly 3 colons, so we need to normalize any colon-fences
+# that don't match Quarto cell patterns back to 3 colons.
+# This regex matches lines with 3+ colons that aren't Quarto cell syntax:
+# - Matches: `::::: module.path` (mkdocstrings), `:::::` (closing fence)
+# - Doesn't match: `:::: {.cell ...}` (has braces), handled by other regexes
+MKDOCSTRINGS_NORMALIZE_REGEX: Final = re.compile(r"^(:{3,})(\s+(?!{).*)?$")
+
 # https://squidfunk.github.io/mkdocs-material/reference/admonitions/#supported-types
 # ???+ means a collapsable block rendered open by default
 TYPE_MAPPING: Final = {
@@ -71,11 +83,7 @@ class FileContent:
     lines: list[str]
 
     def get_line_content(self, cursor: Cursor) -> str:
-        try:
-            line = self.lines[cursor.line]
-        except IndexError:
-            breakpoint()
-        # Return line content from the cursor column
+        line = self.lines[cursor.line]
         return line[cursor.col :]
 
     def _trim_line(
@@ -138,7 +146,7 @@ class BlockContext:
     end: Cursor | UnknownEnd
 
     def __post_init__(self):
-        log.info(f"BlockContext: {self}")
+        log.debug(f"BlockContext: {self}")
 
     def get_content(self, file_content: FileContent) -> str:
         return file_content.get_lines_content(self.start, self.end)
@@ -430,16 +438,41 @@ def run(self, lines):
 
             else:
                 line = file_content.get_line_content(cursor)
+                # Normalize mkdocstrings syntax that Quarto wrapped in extra colons
+                # This only affects lines that didn't match any Quarto block patterns
+                if match := MKDOCSTRINGS_NORMALIZE_REGEX.match(line):
+                    # Double-check this isn't a Quarto pattern (shouldn't be, but be safe)
+                    if not (
+                        CELL_REGEX.match(line)
+                        or CELL_ELEM_REGEX.match(line)
+                        or CELL_ELEM_ALT_REGEX.match(line)
+                    ):
+                        rest = match.group(2) or ""
+                        line = ":::" + rest
+                        log.debug(
+                            f"Normalized mkdocstrings: {match.group(0).strip()!r} -> {line.strip()!r}"
+                        )
                 outs.append(line)
                 cursor = cursor.advance_line(1)
 
         if any(x.startswith(":::") for x in outs):
-            # the ':::' is used in quarto to denote blocks but also used in
-            # mkdocstrings as a special 'domain-specific-syntax' ... so we need
-            # to remove them .... it also points to a bug in the preprocessor
-            # that let them go through ...
-            bads = [x for x in outs if x.startswith(":::")]
-            raise ValueError(f"Cell data contains admonition: {bads}")
+            # Check if these are unprocessed Quarto cell blocks (which would be a bug)
+            # vs. mkdocstrings syntax or other valid uses of ::: (which should be allowed)
+            potential_bugs = []
+            for x in outs:
+                if x.startswith(":::"):
+                    # Check if it looks like Quarto cell syntax that escaped processing
+                    if (
+                        CELL_REGEX.match(x)
+                        or CELL_ELEM_REGEX.match(x)
+                        or CELL_ELEM_ALT_REGEX.match(x)
+                    ):
+                        potential_bugs.append(x)
+
+            if potential_bugs:
+                raise ValueError(
+                    f"Unprocessed Quarto cell syntax found: {potential_bugs}"
+                )
         return outs
 
 

mkquartodocs/logging.py

@@ -24,8 +24,6 @@
 import logging
 from typing import Any, MutableMapping, Tuple
 
-from mkdocs.utils import warning_filter
-
 
 class LoggerAdapter(logging.LoggerAdapter):
     """A logger adapter to prefix messages."""
@@ -63,5 +61,4 @@ def get_logger(name: str) -> LoggerAdapter:
         A logger configured to work well in MkDocs.
     """
     logger = logging.getLogger(f"mkdocs.plugins.{name}")
-    logger.addFilter(warning_filter)
     return LoggerAdapter(name.split(".", 1)[0], logger)

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mkquartodocs"
-version = "0.6.0"
+version = "0.7.0"
 description = ""
 authors = [
   { name = "J. Sebastian Paez", email = "[email protected]" },
@@ -23,6 +23,8 @@ check = [
   "pytest-datadir>=1.3.1",
   "pytest>=8.3.1",
   "pytest-cov>=4.0.0",
+  "syrupy>=4.0.0",
+  "pyyaml>=6.0.0",
   "mdformat>=0.7.16",
   "mdformat-black>=0.1.1",
   "mdformat-config>=0.1.3",