Feat/mdformat extensions

pyproject.toml

@@ -87,6 +87,7 @@ ci = [
     "duty>=1.6",
     "griffe>=2.0",
     "inline-snapshot>=0.6",
+    "mdformat-tables>=1.0",
     "pytest>=8.2",
     "pytest-cov>=5.0",
     "pytest-randomly>=3.15",

src/griffe2md/_internal/cli.py

@@ -16,7 +16,7 @@
 from typing import Any
 
 from griffe2md._internal import debug
-from griffe2md._internal.config import load_config
+from griffe2md._internal.config import ConfigDict, load_config
 from griffe2md._internal.main import write_package_docs
 
 
@@ -44,6 +44,12 @@ def get_parser() -> argparse.ArgumentParser:
         help="Whether to format the resulting Markdown using `mdformat`.",
     )
     parser.add_argument("-o", "--output", default=None, help="File to write to. Default: stdout.")
+    parser.add_argument(
+        "--mdformat-extensions",
+        nargs="*",
+        default=[],
+        help="mdformat extensions to enable (e.g. 'tables'). Requires the corresponding mdformat plugin to be installed.",
+    )
     parser.add_argument("-V", "--version", action="version", version=f"%(prog)s {debug._get_version()}")
     parser.add_argument("--debug-info", action=_DebugInfo, help="Print debug information.")
     return parser
@@ -64,5 +70,9 @@ def main(args: list[str] | None = None) -> int:
     opts = parser.parse_args(args=args)
     config = load_config()
 
+    if opts.mdformat_extensions:
+        config = ConfigDict() if config is None else config
+        config["mdformat_extensions"] = opts.mdformat_extensions
+
     write_package_docs(opts.package, config, opts.output, format_md=opts.format_md)
     return 0

src/griffe2md/_internal/config.py

@@ -103,6 +103,14 @@ class ConfigDict(TypedDict, total=False):
     load_external_modules: bool
     """Whether to always load external modules/packages."""
 
+    mdformat_extensions: list[str]
+    """A list of mdformat extensions to enable when formatting Markdown output.
+
+    For example, `["tables"]` to enable the `mdformat-tables` extension,
+    which properly handles escaped pipes in table cells.
+    Users are responsible for installing such extensions in the environment.
+    """
+
     members: list[str] | bool | None
     """A boolean, or an explicit list of members to render.
 

src/griffe2md/_internal/main.py

@@ -137,7 +137,8 @@ def render_object_docs(obj: Object, config: ConfigDict | None = None, *, format_
     context = prepare_context(obj, config)
     rendered = env.get_template(f"{obj.kind.value}.md.jinja").render(**context)
     if format_md:
-        rendered = mdformat.text(rendered)
+        mdformat_ext = (config or {}).get("mdformat_extensions", [])
+        rendered = mdformat.text(rendered, extensions=mdformat_ext)
     return rendered
 
 

tests/test_rendering.py

@@ -0,0 +1,62 @@
+import griffe
+from inline_snapshot import snapshot
+
+from griffe2md import render_object_docs
+
+
+def test_mdformat_extensions() -> None:
+    docstring = griffe.Docstring(
+        """A docstring with a table.
+
+        Header 1  | Header 2
+        ------ | ---
+        Cell 1    | Cell 2
+        """,
+    )
+    attribute = griffe.Attribute(name="render_me", parent=None, value="...", docstring=docstring)
+
+    not_formatted = render_object_docs(attribute, format_md=False).strip("\n") + "\n"
+    assert not_formatted == snapshot("""\
+## `render_me`
+
+```python
+render_me = ...
+```
+
+A docstring with a table.
+
+Header 1  | Header 2
+------ | ---
+Cell 1    | Cell 2
+""")
+
+    formatted_no_table = render_object_docs(attribute, format_md=True).strip("\n") + "\n"
+    assert formatted_no_table == snapshot("""\
+## `render_me`
+
+```python
+render_me = ...
+```
+
+A docstring with a table.
+
+Header 1 | Header 2
+------ | ---
+Cell 1 | Cell 2
+""")
+    formatted_table = (
+        render_object_docs(attribute, config={"mdformat_extensions": ["tables"]}, format_md=True).strip("\n") + "\n"
+    )
+    assert formatted_table == snapshot("""\
+## `render_me`
+
+```python
+render_me = ...
+```
+
+A docstring with a table.
+
+| Header 1 | Header 2 |
+| -------- | -------- |
+| Cell 1   | Cell 2   |
+""")