feat: add option for tabulating variables (#693)

ansibledoctor/config.py

@@ -123,6 +123,12 @@ class Config:
             "file": True,
             "type": environs.Env().bool,
         },
+        "tabulate_variables": {
+            "default": False,
+            "env": "TABULATE_VARIABLES",
+            "file": True,
+            "type": environs.Env().bool,
+        },
     }
 
     ANNOTATIONS = {

ansibledoctor/doc_generator.py

@@ -123,7 +123,10 @@ class Generator:
                             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)
+                            tabulate_vars = self.config.config.get("tabulate_variables")
+                            data = jenv.from_string(data).render(
+                                role_data, role=role_data, tabulate_vars=tabulate_vars
+                            )
                             if not self.config.config["dry_run"]:
                                 with open(doc_file, "wb") as outfile:
                                     outfile.write(header_content.encode("utf-8"))

ansibledoctor/templates/hugo-book/_toc.j2

@@ -2,10 +2,12 @@
 {% set var = role.var | default({}) %}
 {% if var %}
 - [Default Variables](#default-variables)
+{% if not tabulate_vars %}
 {% for key, item in var | dictsort %}
   - [{{ key }}](#{{ key }})
 {% endfor %}
 {% endif %}
+{% endif %}
 {% if tag %}
 - [Discovered Tags](#discovered-tags)
 {% endif %}

ansibledoctor/templates/hugo-book/_vars_tabulated.j2

@@ -0,0 +1,36 @@
+{% set var = role.var | default({}) %}
+{% if var %}
+## Default Variables
+
+{% set columns = ["variable", "default", "description", "type", "deprecated", "example"] %}
+{% set found_columns = ["variable", "default"] + var.values() | map("list") | sum(start=["key"]) | unique | list %}
+{% for c in columns %}
+{% if c in found_columns %}
+| {{ c | capitalize }} {# trimnewline #}
+{% endif %}
+{% endfor %}
+|
+{% for c in columns %}
+{% if c in found_columns %}
+| {{ "-" * (c | length) }} {# trimnewline #}
+{% endif %}
+{% endfor %}
+|
+{% for key, item in var | dictsort %}
+| {{ key }} {# trimnewline #}
+| {{ (item.value | default({}))[key] | default }} {# trimnewline #}
+{% if "description" in found_columns %}
+| {{ item.description | default([]) | safe_join("<br>") | replace("\n", "<br>") | replace("|", "\|") }} {# trimnewline #}
+{% endif %}
+{% if "type" in found_columns %}
+| {{ item.type | default([]) | join("<br>") }} {# trimnewline #}
+{% endif %}
+{% if "deprecated" in found_columns %}
+| {{ item.deprecated | default }} {# trimnewline #}
+{% endif %}
+{% if "example" in found_columns %}
+| {{ item.example | default([]) | safe_join("<br>") | replace("\n", "<br>") | replace("|", "\|") }} {# trimnewline #}
+{% endif %}
+|
+{% endfor %}
+{% endif %}

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

@@ -23,7 +23,11 @@ summary: {{ meta.summary.value | safe_join(" ") }}
 {% include '_requirements.j2' %}
 
 {#      Vars      #}
+{% if tabulate_vars %}
+{% include '_vars_tabulated.j2' %}
+{% else %}
 {% include '_vars.j2' %}
+{% endif %}
 
 {#      Tag      #}
 {% include '_tag.j2' %}

ansibledoctor/templates/readme/README.md.j2

@@ -15,7 +15,11 @@
 {% include '_requirements.j2' %}
 
 {#      Vars      #}
+{% if tabulate_vars %}
+{% include '_vars_tabulated.j2' %}
+{% else %}
 {% include '_vars.j2' %}
+{% endif %}
 
 {#      Tag      #}
 {% include '_tag.j2' %}

ansibledoctor/templates/readme/_toc.j2

@@ -4,10 +4,12 @@
 {% set var = role.var | default({}) %}
 {% if var %}
 - [Default Variables](#default-variables)
+{% if not tabulate_vars %}
 {% for key, item in var | dictsort %}
   - [{{ key }}](#{{ key }})
 {% endfor %}
 {% endif %}
+{% endif %}
 {% if tag %}
 - [Discovered Tags](#discovered-tags)
 {% endif %}

ansibledoctor/templates/readme/_vars_tabulated.j2

@@ -0,0 +1,36 @@
+{% set var = role.var | default({}) %}
+{% if var %}
+## Default Variables
+
+{% set columns = ["variable", "default", "description", "type", "deprecated", "example"] %}
+{% set found_columns = ["variable", "default"] + var.values() | map("list") | sum(start=["key"]) | unique | list %}
+{% for c in columns %}
+{% if c in found_columns %}
+| {{ c | capitalize }} {# trimnewline #}
+{% endif %}
+{% endfor %}
+|
+{% for c in columns %}
+{% if c in found_columns %}
+| {{ "-" * (c | length) }} {# trimnewline #}
+{% endif %}
+{% endfor %}
+|
+{% for key, item in var | dictsort %}
+| {{ key }} {# trimnewline #}
+| {{ (item.value | default({}))[key] | default }} {# trimnewline #}
+{% if "description" in found_columns %}
+| {{ item.description | default([]) | safe_join("<br>") | replace("\n", "<br>") | replace("|", "\|") }} {# trimnewline #}
+{% endif %}
+{% if "type" in found_columns %}
+| {{ item.type | default([]) | join("<br>") }} {# trimnewline #}
+{% endif %}
+{% if "deprecated" in found_columns %}
+| {{ item.deprecated | default }} {# trimnewline #}
+{% endif %}
+{% if "example" in found_columns %}
+| {{ item.example | default([]) | safe_join("<br>") | replace("\n", "<br>") | replace("|", "\|") }} {# trimnewline #}
+{% endif %}
+|
+{% endfor %}
+{% endif %}