fix: unify value format of tabulated vars (#792)

ansibledoctor/doc_generator.py

@@ -1,6 +1,7 @@
 #!/usr/bin/env python3
 """Prepare output and write compiled jinja2 templates."""
 
+import json
 import os
 import re
 from functools import reduce
@@ -128,7 +129,7 @@ class Generator:
         yaml.dump(a, stream, **kw)
         return stream.getvalue().rstrip()
 
-    def _to_code(self, a, to_multiline=False, skip_list_len=0, lang="plain"):
+    def _to_code(self, a, to_multiline=False, tab_var=False, preserve_ms=False, lang="plain"):
         """Wrap a string in backticks."""
         if a is None or a == "":
             return ""
@@ -136,16 +137,23 @@ class Generator:
         if (isinstance(a, list) and len(a) < 1) or (isinstance(a, dict) and not a):
             return ""
 
-        if isinstance(a, list) and len(a) == 1:
-            return f"`{a[0]}`"
-
-        if isinstance(a, list) and skip_list_len > 0 and len(a) > skip_list_len:
+        if isinstance(a, list) and len(a) > 1 and preserve_ms:
             return a
 
+        if isinstance(a, list) and len(a) == 1:
+            return f"`{self._tab_var(a[0], tab_var)}`"
+
         if (isinstance(a, list)) and to_multiline:
             return "```" + lang + "\n" + "\n".join(a) + "\n```"
 
-        return f"`{a}`"
+        return f"`{self._tab_var(a, tab_var)}`"
+
+    def _tab_var(self, a, tab_var):
+        """Wrap a string in backticks."""
+        if not tab_var:
+            return a
+
+        return json.dumps(a)
 
     def _deep_get(self, _, dictionary, keys):
         default = None

ansibledoctor/templates/readme/_vars_tabulated.j2

@@ -18,12 +18,12 @@
 |
 {% for key, item in var | dictsort %}
 |{{ key | to_code -}}
-|{{ (item.value | default({}))[key] | default | to_code -}}
+|{{ (item.value | default({}))[key] | default | to_code(tab_var=true) -}}
 {% if "description" in found_columns %}
 |{{ item.description | default([]) | safe_join("<br />") | replace("\n", "<br />") | replace("|", "\|") -}}
 {% endif %}
 {% if "type" in found_columns %}
-|{{ item.type | default([]) | to_code(skip_list_len=1) | safe_join("<br />") -}}
+|{{ item.type | default([]) | to_code(preserve_ms=true) | safe_join("<br />") -}}
 {% endif %}
 {% if "deprecated" in found_columns %}
 |
@@ -42,7 +42,7 @@ False
 {% endif %}
 {% endif %}
 {% if "example" in found_columns %}
-|{{ item.example | default([]) | to_code(skip_list_len=1) | safe_join("<br />") | replace("\n", "<br />") | replace("|", "\|") -}}
+|{{ item.example | default([]) | to_code(tab_var=true,preserve_ms=true) | safe_join("<br />") | replace("\n", "<br />") | replace("|", "\|") -}}
 {% endif %}
 |
 {% endfor %}

example/other-role/README.md

@@ -9,7 +9,7 @@ Role to demonstrate ansible-doctor.
 
 - [Requirements](#requirements)
 - [Default Variables](#default-variables)
-  - [demo_bool](#demo_bool)
+  - [other_role_bool](#other_role_bool)
   - [other_role_deprecated](#other_role_deprecated)
   - [other_role_deprecated_info](#other_role_deprecated_info)
   - [other_role_dict](#other_role_dict)
@@ -36,18 +36,18 @@ Role to demonstrate ansible-doctor.
 
 ## Default Variables
 
-### demo_bool
+### other_role_bool
 
 #### Default value
 
 ```YAML
-demo_bool: true
+other_role_bool: true
 ```
 
 #### Example usage
 
 ```YAML
-demo_bool: false
+other_role_bool: false
 ```
 
 ### other_role_deprecated

example/other-role/defaults/main.yml

@@ -6,8 +6,8 @@ other_role_unset:
 other_role_empty: ""
 other_role_single: "b"
 
-# @var demo_bool:example: $ false
-demo_bool: true
+# @var other_role_bool:example: $ false
+other_role_bool: True
 
 # @var other_role_empty_dict:description: >
 # ... or valid json can be used. In this case, the json will be automatically prefixed with the annotation key