refactor: Don't format code with mdformat by default

Now that we improved our templates to directly output the correct spacing between items, we shouldn't need to format the Markdown with `mdformat` by default.

Therefore, we change the default value of the `format_md` parameter to false.

This shouldn't be a breaking change for users not passing any value, and users passing true will keep getting their Markdown with `mdformat`.

Issue-19: #19

Author: pawamoy

pyproject.toml

@@ -31,6 +31,7 @@ classifiers = [
 dependencies = [
     "griffelib>=2.0",
     "jinja2>=3.1.2",
+    # TODO: Make this an optional dependency at some point.
     "mdformat>=0.7.16",
     # YORE: EOL 3.10: Remove line.
     "tomli>=2.0; python_version < '3.11'",

src/griffe2md/_internal/cli.py

@@ -37,6 +37,12 @@ def get_parser() -> argparse.ArgumentParser:
     """
     parser = argparse.ArgumentParser(prog="griffe2md")
     parser.add_argument("package", help="The package to output Markdown docs for.")
+    parser.add_argument(
+        "-f",
+        "--format-md",
+        action="store_true",
+        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("-V", "--version", action="version", version=f"%(prog)s {debug._get_version()}")
     parser.add_argument("--debug-info", action=_DebugInfo, help="Print debug information.")
@@ -58,5 +64,5 @@ def main(args: list[str] | None = None) -> int:
     opts = parser.parse_args(args=args)
     config = load_config()
 
-    write_package_docs(opts.package, config, opts.output)
+    write_package_docs(opts.package, config, opts.output, format_md=opts.format_md)
     return 0

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 = True) -> str:
+def render_object_docs(obj: Object, config: ConfigDict | None = None, *, format_md: bool = False) -> str:
     """Render docs for a given object.
 
     Parameters:
@@ -141,7 +141,7 @@ def render_object_docs(obj: Object, config: ConfigDict | None = None, *, format_
     return rendered
 
 
-def render_package_docs(package: str, config: ConfigDict | None = None, *, format_md: bool = True) -> str:
+def render_package_docs(package: str, config: ConfigDict | None = None, *, format_md: bool = False) -> str:
     """Render docs for a given package.
 
     Parameters:
@@ -174,7 +174,7 @@ def write_package_docs(
     config: ConfigDict | None = None,
     output: IO | str | None = None,
     *,
-    format_md: bool = True,
+    format_md: bool = False,
 ) -> None:
     """Write docs for a given package to a file or stdout.
 

tests/test_config.py

@@ -30,4 +30,4 @@ def test_load_config(tmpdir: py.path.local, rel_path: Path) -> None:
 
         griffe2md.main(["griffe2md"])
 
-    mock_write.assert_called_once_with("griffe2md", expected_config, None)
+    mock_write.assert_called_once_with("griffe2md", expected_config, None, format_md=False)