fix: join lines with newline instead of space in markdown templates (#446)

.markdownlint.yml

@@ -2,5 +2,6 @@
 default: True
 MD013: False
 MD041: False
+MD024: False
 MD004:
   style: dash

ansibledoctor/doc_generator.py

@@ -119,7 +119,9 @@ class Generator:
                             )
                             jenv.filters["to_nice_yaml"] = self._to_nice_yaml
                             jenv.filters["deep_get"] = self._deep_get
-                            jenv.filters["save_join"] = self._save_join
+                            jenv.filters["safe_join"] = self._safe_join
+                            # keep the old name of the function to not break custom templates.
+                            jenv.filters["save_join"] = self._safe_join
                             data = jenv.from_string(data).render(role_data, role=role_data)
                             if not self.config.config["dry_run"]:
                                 with open(doc_file, "wb") as outfile:
@@ -129,7 +131,9 @@ class Generator:
                             else:
                                 self.logger.info(f"Writing to: {doc_file}")
                         except (
-                            jinja2.exceptions.UndefinedError, jinja2.exceptions.TemplateSyntaxError
+                            jinja2.exceptions.UndefinedError,
+                            jinja2.exceptions.TemplateSyntaxError,
+                            jinja2.exceptions.TemplateRuntimeError
                         ) as e:
                             self.log.sysexit_with_message(
                                 "Jinja2 templating error while loading file: '{}'\n{}".format(
@@ -157,7 +161,7 @@ class Generator:
         )
 
     @pass_eval_context
-    def _save_join(self, eval_ctx, value, d=""):
+    def _safe_join(self, eval_ctx, value, d=""):
         if isinstance(value, str):
             value = [value]
 

ansibledoctor/templates/hugo-book/_tag.j2

@@ -4,8 +4,8 @@
 {% for key, item in tag | dictsort %}
 
 {{ key }}
-{% if item.description is defined and item.description | save_join(" ") | striptags %}
-: {{ item.description | save_join(" ") | striptags }}
+{% if item.description is defined and item.description | safe_join(" ") | striptags %}
+: {{ item.description | safe_join(" ") | striptags }}
 {% else %}
 :  
 {% endif %}

ansibledoctor/templates/hugo-book/_todo.j2

@@ -4,15 +4,15 @@
 
 {% for key, item in todo | dictsort %}
 {% for line in item %}
-{% if line.value is defined and line.value | save_join(" ") | striptags and key == "default" %}
-- {{ line.value | save_join(" ") | striptags }}
+{% if line.value is defined and line.value | safe_join(" ") | striptags and key == "default" %}
+- {{ line.value | safe_join(" ") | striptags }}
 {% endif %}
 {% endfor %}
 {% endfor %}
 {% for key, item in todo | dictsort %}
 {% for line in item %}
-{% if line.value is defined and line.value | save_join(" ") | striptags and key != "default" %}
-- ({{ key }}): {{ line.value | save_join(" ") | striptags }}
+{% if line.value is defined and line.value | safe_join(" ") | striptags and key != "default" %}
+- ({{ key }}): {{ line.value | safe_join(" ") | striptags }}
 {% endif %}
 {% endfor %}
 {% endfor %}

ansibledoctor/templates/hugo-book/_vars.j2

@@ -7,7 +7,7 @@
 ### {{ key }}
 {% if item.description is defined and item.description %}
 
-{{ item.description | save_join(" ") }}
+{{ item.description | map("replace", "\n\n", "\n") | safe_join("\n") }}
 {% endif %}
 {% if item.value is defined and item.value %}
 

ansibledoctor/templates/hugo-book/index.md.j2

@@ -1,16 +1,16 @@
 {% if not append | deep_get(role, "internal.append") %}
 {% set meta = role.meta | default({}) %}
 ---
-title: {{ meta.name.value | save_join(" ") }}
+title: {{ meta.name.value | safe_join(" ") }}
 type: docs
 {% if summary | deep_get(meta, "summary.value") %}
-summary: {{ meta.summary.value | save_join(" ") }}
+summary: {{ meta.summary.value | safe_join(" ") }}
 {% endif %}
 ---
 {% endif %}
 {% if description | deep_get(meta, "description.value") %}
 
-{{ meta.description.value | save_join(" ") }}
+{{ meta.description.value | map("replace", "\n\n", "\n") | safe_join("\n") }}
 {% endif %}
 
 <!--more-->

ansibledoctor/templates/readme/README.md.j2

@@ -1,10 +1,10 @@
 {% if not append | deep_get(role, "internal.append") %}
 {% set meta = role.meta | default({}) %}
-# {{ meta.name.value | save_join(" ") }}
+# {{ meta.name.value | safe_join(" ") }}
 {% endif %}
 {% if description | deep_get(meta, "description.value") %}
 
-{{ meta.description.value | save_join(" ") }}
+{{ meta.description.value | map("replace", "\n\n", "\n") | safe_join("\n") }}
 {% endif %}
 
 {#      TOC      #}

ansibledoctor/templates/readme/_meta.j2

@@ -26,6 +26,6 @@ None.
 
 ## Author
 
-{{ meta.author.value | save_join(" ") }}
+{{ meta.author.value | safe_join(" ") }}
 {% endif %}
 {% endif %}

ansibledoctor/templates/readme/_tag.j2

@@ -2,11 +2,11 @@
 {% if tag %}
 ## Discovered Tags
 {% for key, item in tag | dictsort %}
-{% set is_desc = item.description is defined and item.description | save_join(" ") | striptags %}
+{% set is_desc = item.description is defined and item.description | safe_join(" ") | striptags %}
 
 **_{{ key }}_**{{ "\\" if is_desc else "" }}
 {% if is_desc %}
- {{ item.description | save_join(" ") | striptags }}
+ {{ item.description | safe_join(" ") | striptags }}
 {% endif %}
 {% endfor %}
 {% endif %}

ansibledoctor/templates/readme/_todo.j2

@@ -4,15 +4,15 @@
 
 {% for key, item in todo | dictsort %}
 {% for line in item %}
-{% if line.value is defined and line.value | save_join(" ") | striptags and key == "default" %}
-- {{ line.value | save_join(" ") | striptags }}
+{% if line.value is defined and line.value | safe_join(" ") | striptags and key == "default" %}
+- {{ line.value | safe_join(" ") | striptags }}
 {% endif %}
 {% endfor %}
 {% endfor %}
 {% for key, item in todo | dictsort %}
 {% for line in item %}
-{% if line.value is defined and line.value | save_join(" ") | striptags and key != "default" %}
-- ({{ key }}): {{ line.value | save_join(" ") | striptags }}
+{% if line.value is defined and line.value | safe_join(" ") | striptags and key != "default" %}
+- ({{ key }}): {{ line.value | safe_join(" ") | striptags }}
 {% endif %}
 {% endfor %}
 {% endfor %}

ansibledoctor/templates/readme/_vars.j2

@@ -7,7 +7,7 @@
 ### {{ key }}
 {% if item.description is defined and item.description %}
 
-{{ item.description | save_join(" ") }}
+{{ item.description | map("replace", "\n\n", "\n") | safe_join("\n") }}
 {% endif %}
 {% if item.value is defined and item.value %}
 

example/README.md

@@ -3,7 +3,8 @@
 [![Build Status](https://img.shields.io/drone/build/thegeeklab/ansible-doctor?logo=drone&server=https%3A%2F%2Fdrone.thegeeklab.de)](https://drone.thegeeklab.de/thegeeklab/ansible-doctor)
 [![License: GPL-3.0](https://img.shields.io/github/license/thegeeklab/ansible-doctor)](https://github.com/thegeeklab/ansible-doctor/blob/main/LICENSE)
 
-Role to demonstrate ansible-doctor. It is also possible to overwrite the default description with an annotation.
+Role to demonstrate ansible-doctor. It is also possible to overwrite
+the default description with an annotation.
 
 ## Table of content
 
@@ -61,7 +62,8 @@ demo_role_empty: ''
 
 ### demo_role_empty_dict
 
-... or valid json can be used. In this case, the json will be automatically prefixed with the annotation key and filters like `to_nice_yaml` can be used in templates. To get it working, the json need to be prefixed with a `$`.
+... or valid json can be used. In this case, the json will be automatically prefixed with the annotation key
+and filters like `to_nice_yaml` can be used in templates. To get it working, the json need to be prefixed with a `$`.
 
 #### Default value
 
@@ -127,7 +129,12 @@ demo_role_single: b
 
 ### demo_role_undefined_var
 
-To highlight a variable that has not set a value by default, this is one way to achieve it. Make sure to flag it as json value: `@var demo_role_undefined_var: $ "_unset_"`
+To highlight a variable that has not set a value by default, this is one way to achieve it.
+Make sure to flag it as json value: `@var demo_role_undefined_var: $ "_unset_"`
+
+| Attribute | Description |
+| --- | --- |
+| value1 | desc1 |
 
 #### Default value
 

example/demo-role/defaults/main.yml

@@ -31,6 +31,11 @@ demo_role_dict:
 # @var demo_role_undefined_var:description: >
 # To highlight a variable that has not set a value by default, this is one way to achieve it.
 # Make sure to flag it as json value: `@var demo_role_undefined_var: $ "_unset_"`
+#
+# | Attribute | Description |
+# | --- | --- |
+# | value1 | desc1 |
+#
 # @end
 # @var demo_role_undefined_var: $ "_unset_"