feat: Improve spacing in templates directly

Issue-19: #19

Author: pawamoy

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

@@ -85,6 +85,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/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 -%}

src/griffe2md/templates/docstring/attributes.md.jinja

@@ -1,5 +1,4 @@
-{%- if config.docstring_section_style == "table" %}
-
+{%- if config.docstring_section_style == "table" -%}
 **{{ section.title or "Attributes:" }}**
 
 Name | Type | Description
@@ -8,10 +7,9 @@ Name | Type | Description
 [`{{ attribute.name }}`](#{{ obj.path }}.{{ attribute.name }}) | {% if attribute.annotation -%}{%- with expression = attribute.annotation -%}<code>{% filter replace("|", "\\|") %}{%- include "expression.md.jinja" with context -%}{% endfilter %}</code>{%- endwith -%}{%- endif %} | {{ attribute.description|newline_to_br }}
 {%- endfor -%}
 
-{%- elif config.docstring_section_style == "list" %}
-
+{%- elif config.docstring_section_style == "list" -%}
 **{{ section.title or "Attributes:" }}**
 {% for attribute in section.value %}
 - [**{{ attribute.name }}**](#{{ obj.path }}.{{ attribute.name }}){%- if attribute.annotation -%}{%- with expression = attribute.annotation %} (<code>{%- include "expression.md.jinja" with context -%}</code>){%- endwith -%}{%- endif %} – {{ attribute.description }}
 {%- endfor -%}
-{%- endif -%}
+{%- endif %}

src/griffe2md/templates/docstring/classes.md.jinja

@@ -1,5 +1,4 @@
-{%- if config.docstring_section_style == "table" %}
-
+{%- if config.docstring_section_style == "table" -%}
 **{{ section.title or "Classes:" }}**
 
 Name | Description
@@ -8,10 +7,9 @@ Name | Description
 [`{{ class.name }}`](#{{ obj.path }}.{{ class.name }}) | {{ class.description|newline_to_br }}
 {%- endfor -%}
 
-{%- elif config.docstring_section_style == "list" %}
-
+{%- elif config.docstring_section_style == "list" -%}
 **{{ section.title or "Classes:" }}**
 {% for class in section.value %}
 - [**{{ class.name }}**](#{{ obj.path }}.{{ class.name }}) – {{ class.description }}
 {%- endfor -%}
-{%- endif -%}
+{%- endif -%}

src/griffe2md/templates/docstring/examples.md.jinja

@@ -3,8 +3,8 @@
 {% for section_type, sub_section in section.value -%}
 {%- if section_type.value == "text" -%}
 {{ sub_section }}
-{%- elif section_type.value == "examples" %}
 
+{% elif section_type.value == "examples" -%}
 ```pycon
 {{ sub_section }}
 ```