Merge branch 'main' into feat/mdformat-extensions

Author: deven367

CHANGELOG.md

@@ -6,6 +6,19 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
 <!-- insertion marker -->
+## [1.4.0](https://github.com/mkdocstrings/griffe2md/releases/tag/1.4.0) - 2026-03-06
+
+<small>[Compare with 1.3.4](https://github.com/mkdocstrings/griffe2md/compare/1.3.4...1.4.0)</small>
+
+### Features
+
+- Improve spacing in templates directly ([58e7126](https://github.com/mkdocstrings/griffe2md/commit/58e7126435573b18b040a2f22c71d29d99126c38) by Timothée Mazzucotelli). [Issue-19](https://github.com/mkdocstrings/griffe2md/issues/19)
+
+### Code Refactoring
+
+- Don't format code with mdformat by default ([6b8928f](https://github.com/mkdocstrings/griffe2md/commit/6b8928f00119c4b149e597690fe03f2e053ce077) by Timothée Mazzucotelli). [Issue-19](https://github.com/mkdocstrings/griffe2md/issues/19)
+- Mark configuration typed dict as non-total ([3636cab](https://github.com/mkdocstrings/griffe2md/commit/3636cab3bd6546482b11393b29c2cb8445dd7a7f) by Timothée Mazzucotelli).
+
 ## [1.3.4](https://github.com/mkdocstrings/griffe2md/releases/tag/1.3.4) - 2026-02-20
 
 <small>[Compare with 1.3.3](https://github.com/mkdocstrings/griffe2md/compare/1.3.3...1.3.4)</small>

config/ruff.toml

@@ -53,6 +53,7 @@ ignore = [
     "ARG005",  # Unused lambda argument
     "FBT001",  # Boolean positional arg in function definition
     "PLR2004",  # Magic value used in comparison
+    "RUF001",  # String contains ambiguous `–` (EN DASH)
     "S101",  # Use of assert detected
 ]
 

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'",
@@ -85,6 +86,7 @@ maintain = [
 ci = [
     "duty>=1.6",
     "griffe>=2.0",
+    "inline-snapshot>=0.6",
     "pytest>=8.2",
     "pytest-cov>=5.0",
     "pytest-randomly>=3.15",

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(
         "--mdformat-extensions",

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:
@@ -143,7 +143,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:
@@ -176,7 +176,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.
 

src/griffe2md/_internal/rendering.py

@@ -261,7 +261,7 @@ def do_order_members(
 
 def do_heading(content: str, heading_level: int) -> str:
     """Render a Markdown heading."""
-    return f"\n{'#' * heading_level} {content}\n\n"
+    return f"{'#' * heading_level} {content}"
 
 
 def do_split_path(path: str, full_path: str) -> list[tuple[str, str]]:
@@ -497,4 +497,4 @@ def do_as_modules_section(modules: Sequence[Module], *, check_public: bool = Tru
 
 
 def _newline_to_br(text: str) -> str:
-    return text.replace("\n\n", "<br>").replace("\n", " ")
+    return text.replace("\n\n", "<br>").strip().replace("\n", " ")

src/griffe2md/templates/attribute.md.jinja

@@ -9,14 +9,16 @@
 {%- endif -%}
 
 {%- with obj = attribute, attribute_name = attribute.path if show_full_path else attribute.name -%}
-{%- if not root or config.show_root_heading %}
+{%- if not root or config.show_root_heading -%}
 
-{% filter heading(heading_level) -%}
+{%- filter heading(heading_level) -%}
 {%- if config.separate_signature -%}
 `{{ attribute_name }}`
-{%- else -%}
+
+{% else -%}
 `{{- attribute_name }}{% if attribute.annotation -%}: {{ attribute.annotation }}{%- endif -%}`
-{%- endif -%}
+
+{% endif -%}
 {%- endfilter -%}
 
 {%- if config.separate_signature -%}
@@ -27,11 +29,12 @@
 {%- if attribute.value %} = {{ attribute.value|safe }}{%- endif -%}
 {%- endfilter %}
 ```
-{%- endif %}
+
+{% endif -%}
 
 {%- else -%}
-{%- if config.show_root_toc_entry %}
-{% filter heading(heading_level) -%}
+{%- if config.show_root_toc_entry -%}
+{%- filter heading(heading_level) -%}
 {%- endfilter -%}
 {%- endif -%}
 {%- set heading_level = heading_level - 1 -%}
@@ -40,4 +43,4 @@
 {%- with docstring_sections = attribute.docstring.parsed -%}
 {%- include "docstring.md.jinja" with context -%}
 {%- endwith -%}
-{%- endwith -%}
+{%- endwith %}

src/griffe2md/templates/children.md.jinja

@@ -148,7 +148,5 @@ order_members(config.members_order, members_list) -%}
 {%- endif -%}
 
 {%- endfor -%}
-
 {%- endif -%}
-
 {%- endif -%}

src/griffe2md/templates/class.md.jinja

@@ -9,18 +9,21 @@
 {%- endif -%}
 
 {%- with obj = class, class_name = class.path if show_full_path else class.name -%}
-{%- if not root or config.show_root_heading %}
+{%- if not root or config.show_root_heading -%}
 
-{% filter heading(heading_level) -%}
+{%- filter heading(heading_level) -%}
 {%- if config.separate_signature -%}
 `{{ class_name }}`
-{%- elif config.merge_init_into_class and "__init__" in class.members -%}
+
+{% elif config.merge_init_into_class and "__init__" in class.members -%}
 {%- with function = class.members["__init__"] -%}
 `{{ class_name }}{% include "signature.md.jinja" with context %}`
-{%- endwith -%}
+
+{% endwith -%}
 {%- else -%}
 `{{ class_name }}`
-{%- endif -%}
+
+{% endif -%}
 {%- endfilter -%}
 
 {%- if config.separate_signature and config.merge_init_into_class -%}
@@ -64,4 +67,4 @@ Bases: {% for expression in class.bases -%}
 {%- set root = False -%}
 {%- set heading_level = heading_level + 1 -%}
 {%- include "children.md.jinja" with context -%}
-{%- endwith -%}
+{%- endwith %}

src/griffe2md/templates/docstring.md.jinja

@@ -1,27 +1,38 @@
 {%- if docstring_sections -%}
-{% for section in docstring_sections %}
-{% if config.show_docstring_description and section.kind.value == "text" -%}
-{{ section.value }}
+{%- for section in docstring_sections -%}
+{%- if config.show_docstring_description and section.kind.value == "text" -%}
+{{- section.value }}
+
 {% elif config.show_docstring_attributes and section.kind.value == "attributes" -%}
-{% include "docstring/attributes.md.jinja" with context -%}
+{%- include "docstring/attributes.md.jinja" with context %}
+
 {% elif config.show_docstring_parameters and section.kind.value == "parameters" -%}
-{% include "docstring/parameters.md.jinja" with context -%}
+{%- include "docstring/parameters.md.jinja" with context %}
+
 {% elif config.show_docstring_other_parameters and section.kind.value == "other parameters" -%}
-{% include "docstring/other_parameters.md.jinja" with context -%}
+{%- include "docstring/other_parameters.md.jinja" with context %}
+
 {% elif config.show_docstring_raises and section.kind.value == "raises" -%}
-{% include "docstring/raises.md.jinja" with context -%}
+{%- include "docstring/raises.md.jinja" with context %}
+
 {% elif config.show_docstring_warns and section.kind.value == "warns" -%}
-{% include "docstring/warns.md.jinja" with context -%}
+{%- include "docstring/warns.md.jinja" with context %}
+
 {% elif config.show_docstring_yields and section.kind.value == "yields" -%}
-{% include "docstring/yields.md.jinja" with context -%}
+{%- include "docstring/yields.md.jinja" with context %}
+
 {% elif config.show_docstring_receives and section.kind.value == "receives" -%}
-{% include "docstring/receives.md.jinja" with context -%}
+{%- include "docstring/receives.md.jinja" with context %}
+
 {% elif config.show_docstring_returns and section.kind.value == "returns" -%}
-{% include "docstring/returns.md.jinja" with context -%}
+{%- include "docstring/returns.md.jinja" with context %}
+
 {% elif config.show_docstring_examples and section.kind.value == "examples" -%}
-{% include "docstring/examples.md.jinja" with context -%}
-{% elif config.show_docstring_description and section.kind.value == "admonition" -%}
-{% include "docstring/admonition.md.jinja" with context -%}
-{% endif %}
-{% endfor %}
+{%- include "docstring/examples.md.jinja" with context -%}
+
+{%- elif config.show_docstring_description and section.kind.value == "admonition" -%}
+{%- include "docstring/admonition.md.jinja" with context %}
+
+{% endif -%}
+{%- endfor -%}
 {%- endif -%}