From 4051d2915dba76e217926cb062463ef2a00df033 Mon Sep 17 00:00:00 2001
From: Chip Selden <chipselden@gmail.com>
Date: Sat, 1 Jun 2024 13:05:16 -0700
Subject: [PATCH] feat: add option for tabulating variables (#693)

---
 ansibledoctor/config.py                       |  6 ++++
 ansibledoctor/doc_generator.py                |  5 ++-
 ansibledoctor/templates/hugo-book/_toc.j2     |  2 ++
 .../templates/hugo-book/_vars_tabulated.j2    | 36 +++++++++++++++++++
 ansibledoctor/templates/hugo-book/index.md.j2 |  4 +++
 ansibledoctor/templates/readme/README.md.j2   |  4 +++
 ansibledoctor/templates/readme/_toc.j2        |  2 ++
 .../templates/readme/_vars_tabulated.j2       | 36 +++++++++++++++++++
 8 files changed, 94 insertions(+), 1 deletion(-)
 create mode 100644 ansibledoctor/templates/hugo-book/_vars_tabulated.j2
 create mode 100644 ansibledoctor/templates/readme/_vars_tabulated.j2

diff --git a/ansibledoctor/config.py b/ansibledoctor/config.py
index b3c2007..70524a5 100644
--- a/ansibledoctor/config.py
+++ b/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 = {
diff --git a/ansibledoctor/doc_generator.py b/ansibledoctor/doc_generator.py
index 13e06ae..7429062 100644
--- a/ansibledoctor/doc_generator.py
+++ b/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"))
diff --git a/ansibledoctor/templates/hugo-book/_toc.j2 b/ansibledoctor/templates/hugo-book/_toc.j2
index c4ac816..f4517da 100644
--- a/ansibledoctor/templates/hugo-book/_toc.j2
+++ b/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 %}
diff --git a/ansibledoctor/templates/hugo-book/_vars_tabulated.j2 b/ansibledoctor/templates/hugo-book/_vars_tabulated.j2
new file mode 100644
index 0000000..4f73cde
--- /dev/null
+++ b/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 %}
diff --git a/ansibledoctor/templates/hugo-book/index.md.j2 b/ansibledoctor/templates/hugo-book/index.md.j2
index 3d1abfc..c7ae8e5 100644
--- a/ansibledoctor/templates/hugo-book/index.md.j2
+++ b/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' %}
diff --git a/ansibledoctor/templates/readme/README.md.j2 b/ansibledoctor/templates/readme/README.md.j2
index 4d97915..7406327 100644
--- a/ansibledoctor/templates/readme/README.md.j2
+++ b/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' %}
diff --git a/ansibledoctor/templates/readme/_toc.j2 b/ansibledoctor/templates/readme/_toc.j2
index 6dd3108..240652b 100644
--- a/ansibledoctor/templates/readme/_toc.j2
+++ b/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 %}
diff --git a/ansibledoctor/templates/readme/_vars_tabulated.j2 b/ansibledoctor/templates/readme/_vars_tabulated.j2
new file mode 100644
index 0000000..4f73cde
--- /dev/null
+++ b/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 %}