feat: Allow specifying mdformat extensions

Author: deven367

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
@@ -62,7 +68,11 @@ def main(args: list[str] | None = None) -> int:
     """
     parser = get_parser()
     opts = parser.parse_args(args=args)
-    config = load_config()
+    config: ConfigDict | None = 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,13 @@ 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.
+    """
+
     members: list[str] | bool | None
     """A boolean, or an explicit list of members to render.
 

src/griffe2md/_internal/main.py

@@ -116,7 +116,7 @@ def prepare_env(env: Environment | None = None) -> Environment:
     return env
 
 
-def render_object_docs(obj: Object, config: ConfigDict | None = None, *, format_md: bool = False) -> str:
+def render_object_docs(obj: Object, config: ConfigDict | None = None, *, format_md: bool = True) -> str:
     """Render docs for a given object.
 
     Parameters:
@@ -137,11 +137,13 @@ 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)
+        full_config = cast("ConfigDict", {**default_config, **(config or {})})
+        mdformat_ext = full_config.get("mdformat_extensions", [])
+        rendered = mdformat.text(rendered, extensions=mdformat_ext)
     return rendered
 
 
-def render_package_docs(package: str, config: ConfigDict | None = None, *, format_md: bool = False) -> str:
+def render_package_docs(package: str, config: ConfigDict | None = None, *, format_md: bool = True) -> str:
     """Render docs for a given package.
 
     Parameters:
@@ -174,7 +176,7 @@ def write_package_docs(
     config: ConfigDict | None = None,
     output: IO | str | None = None,
     *,
-    format_md: bool = False,
+    format_md: bool = True,
 ) -> None:
     """Write docs for a given package to a file or stdout.
 

tests/test_markdown_spacing.py

@@ -2,13 +2,13 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, cast
 
 import griffe
 import pytest
 from griffe import GriffeLoader, Parser
 
-from griffe2md import render_object_docs
+from griffe2md import ConfigDict, render_object_docs
 
 if TYPE_CHECKING:
     from griffe._internal.models import Module
@@ -74,14 +74,17 @@ def _render(**kwargs: Any) -> str:
 
     return render_object_docs(
         module,
-        {
-            "show_root_full_path": False,
-            "show_root_members_full_path": False,
-            "show_object_full_path": False,
-            "show_category_heading": False,
-            "show_signature": True,
-            **kwargs,
-        },
+        cast(
+            "ConfigDict",
+            {
+                "show_root_full_path": False,
+                "show_root_members_full_path": False,
+                "show_object_full_path": False,
+                "show_category_heading": False,
+                "show_signature": True,
+                **kwargs,
+            },
+        ),
         format_md=False,
     )