fix: allow line-breaks in multiline annotations (#243)

ansibledoctor/doc_generator.py

@@ -4,6 +4,7 @@
 import glob
 import ntpath
 import os
+import re
 from functools import reduce
 
 import jinja2.exceptions
@@ -158,7 +159,10 @@ class Generator:
     def _save_join(self, eval_ctx, value, d=u"", attribute=None):
         if isinstance(value, str):
             value = [value]
-        return jinja2.filters.do_join(eval_ctx, value, d, attribute=None)
+
+        joined = jinja2.filters.do_join(eval_ctx, value, d, attribute=None)
+        nornalized = re.sub(r" +(\n|\t| )", "\\1", joined)
+        return nornalized
 
     def render(self):
         self.logger.info("Using output dir: " + self.config.config.get("output_dir"))

ansibledoctor/templates/hugo-book/_meta.j2

@@ -9,7 +9,7 @@
 {% set deps = meta.dependencies.value %}
 {% endif %}
 {% for item in deps %}
-* {{ item }}
+- {{ item }}
 {% endfor %}
 {% else %}
 None.

ansibledoctor/templates/hugo-book/_toc.j2

@@ -1,10 +1,10 @@
 {% set var = role.var | default({}) %}
 {% if var %}
-* [Default Variables](#default-variables)
+- [Default Variables](#default-variables)
 {% for key, item in var | dictsort %}
-  * [{{ key }}](#{{ key }})
+  - [{{ key }}](#{{ key }})
 {% endfor %}
 {% endif %}
-* [Dependencies](#dependencies)
+- [Dependencies](#dependencies)
 
 ---

ansibledoctor/templates/hugo-book/_vars.j2

@@ -7,7 +7,7 @@
 ### {{ key }}
 {% if item.description is defined and item.description %}
 
-{{ item.description | save_join(" ") | striptags }}
+{{ item.description | save_join(" ") }}
 {% endif %}
 {% if item.value is defined and item.value %}
 
@@ -18,7 +18,7 @@
 {{ item.value | to_nice_yaml(indent=2) }}
 {% else %}
 {% for ve_line in item.value %}
-{{ ve_line }}
+{{ ve_line | replace("\n\n", "\n") }}
 {% endfor %}
 {% endif %}
 ```
@@ -32,7 +32,7 @@
 {{ item.example | to_nice_yaml(indent=2) }}
 {% else %}
 {% for ex_line in item.example %}
-{{ ex_line }}
+{{ ex_line | replace("\n\n", "\n") }}
 {% endfor %}
 {% endif %}
 ```

ansibledoctor/templates/readme/_meta.j2

@@ -9,7 +9,7 @@
 {% set deps = meta.dependencies.value %}
 {% endif %}
 {% for item in deps %}
-* {{ item }}
+- {{ item }}
 {% endfor %}
 {% else %}
 None.

ansibledoctor/templates/readme/_toc.j2

@@ -2,13 +2,13 @@
 
 {% set var = role.var | default({}) %}
 {% if var %}
-* [Default Variables](#default-variables)
+- [Default Variables](#default-variables)
 {% for key, item in var | dictsort %}
-  * [{{ key }}](#{{ key }})
+  - [{{ key }}](#{{ key }})
 {% endfor %}
 {% endif %}
-* [Dependencies](#dependencies)
-* [License](#license)
-* [Author](#author)
+- [Dependencies](#dependencies)
+- [License](#license)
+- [Author](#author)
 
 ---

ansibledoctor/templates/readme/_vars.j2

@@ -7,7 +7,7 @@
 ### {{ key }}
 {% if item.description is defined and item.description %}
 
-{{ item.description | save_join(" ") | striptags }}
+{{ item.description | save_join(" ") }}
 {% endif %}
 {% if item.value is defined and item.value %}
 
@@ -18,7 +18,7 @@
 {{ item.value | to_nice_yaml(indent=2) }}
 {% else %}
 {% for ve_line in item.value %}
-{{ ve_line }}
+{{ ve_line | replace("\n\n", "\n") }}
 {% endfor %}
 {% endif %}
 ```
@@ -32,7 +32,7 @@
 {{ item.example | to_nice_yaml(indent=2) }}
 {% else %}
 {% for ex_line in item.example %}
-{{ ex_line }}
+{{ ex_line | replace("\n\n", "\n") }}
 {% endfor %}
 {% endif %}
 ```

example/README.md

@@ -39,6 +39,8 @@ demo_role_dict:
 demo_role_dict:
   key1:
     sub: some value
+
+  # Inline description
   key2:
     sublist:
       - subval1
@@ -105,6 +107,8 @@ demo_role_single: b
 
 If you want to add an explicit notice, that a var is not set by default, this is one option. Make sure to flag it as json value: `@var demo_role_undefined_var: $ "_unset_"`
 
+Test paragarph
+
 #### Default value
 
 ```YAML

example/demo-role/defaults/main.yml

@@ -4,7 +4,7 @@
 demo_role_unset:
 
 demo_role_empty: ""
-demo_role_single: 'b'
+demo_role_single: "b"
 
 # @var demo_role_empty_dict:description: >
 # ... or you can use a valid json. In this case,
@@ -19,6 +19,8 @@ demo_role_empty_dict: {}
 # demo_role_dict:
 #   key1:
 #     sub: some value
+#
+#   # Inline description
 #   key2:
 #     sublist:
 #       - subval1
@@ -39,9 +41,10 @@ demo_role_dict:
 # ]
 # @end
 demo_role_other_tags: []
-
 # @var demo_role_undefined_var:description: >
-# If you want to add an explicit notice, that a var is not set by default, this is one option.
+# If you want to add an explicit notice, that a var is not set by default,    this is one option.
 # Make sure to flag it as json value: `@var demo_role_undefined_var: $ "_unset_"`
+#
+# Test paragarph
 # @end
 # @var demo_role_undefined_var: $ "_unset_"