Make schema documentation more useful

CODEOWNERS

@@ -6,7 +6,7 @@
 /examples/ @JasonvanBrackel @RothAndrew @jeff-mccoy @YrrepNoj @Racer159
 *.md @Madeline-UX @JasonvanBrackel @RothAndrew @jeff-mccoy @YrrepNoj @Racer159
 
-# Core code 
+# Core code
 /src/ @jeff-mccoy @YrrepNoj @Racer159
 /go.* @jeff-mccoy @YrrepNoj @Racer159
 main.go @jeff-mccoy @YrrepNoj @Racer159
@@ -15,14 +15,15 @@ main.go @jeff-mccoy @YrrepNoj @Racer159
 /packages/ @jeff-mccoy @YrrepNoj @Racer159
 /zarf.yaml @jeff-mccoy @YrrepNoj @Racer159
 
-# Web UI-specific 
-/package*.json @mike-winberry @Racer159 @Noxsios @jeff-mccoy @YrrepNoj 
-/src/internal/api @mike-winberry @Racer159 @Noxsios @jeff-mccoy @YrrepNoj 
-/src/ui/ @mike-winberry @Racer159 @Noxsios @jeff-mccoy @YrrepNoj 
-/playwright.config.ts @mike-winberry @Racer159 @Noxsios @jeff-mccoy @YrrepNoj 
-/svelte.config.js @mike-winberry @Racer159 @Noxsios @jeff-mccoy @YrrepNoj 
-/tsconfig.json @mike-winberry @Racer159 @Noxsios @jeff-mccoy @YrrepNoj 
-/vite.config.ts @mike-winberry @Racer159 @Noxsios @jeff-mccoy @YrrepNoj 
+# Web UI-specific
+/package*.json @mike-winberry @Racer159 @Noxsios @jeff-mccoy @YrrepNoj
+/src/internal/api @mike-winberry @Racer159 @Noxsios @jeff-mccoy @YrrepNoj
+/src/ui/ @mike-winberry @Racer159 @Noxsios @jeff-mccoy @YrrepNoj
+/playwright.config.ts @mike-winberry @Racer159 @Noxsios @jeff-mccoy @YrrepNoj
+/svelte.config.js @mike-winberry @Racer159 @Noxsios @jeff-mccoy @YrrepNoj
+/tsconfig.json @mike-winberry @Racer159 @Noxsios @jeff-mccoy @YrrepNoj
+/vite.config.ts @mike-winberry @Racer159 @Noxsios @jeff-mccoy @YrrepNoj
+/docs-website/ @mike-winberry @Racer159 @Noxsios @jeff-mccoy @YrrepNoj
 
 # Privileged pipeline files
 /.github/ @jeff-mccoy @YrrepNoj @Racer159
@@ -37,5 +38,5 @@ main.go @jeff-mccoy @YrrepNoj @Racer159
 
 # Additional privileged files
 /CODEOWNERS @jeff-mccoy @runyontr
-/cosign.pub @jeff-mccoy @runyontr 
-/LICENSE @jeff-mccoy @runyontr 
+/cosign.pub @jeff-mccoy @runyontr
+/LICENSE @jeff-mccoy @runyontr

hack/jsfh-config.json → docs/.templates/jsfh-config.json

@@ -1,5 +1,5 @@
 {
-  "custom_template_path": "hack/zarf-jsfh-template/base.md",
+  "custom_template_path": "docs/.templates/jsonschemaforhumans/base.md",
   "template_md_options": { "badge_as_image": true, "show_heading_numbers": false },
   "show_toc": false,
   "show_breadcrumbs": false,

hack/zarf-jsfh-template/base.md → docs/.templates/jsonschemaforhumans/base.md

@@ -1,7 +1,6 @@
-{% set depth = 0 %}
-{{ schema.keywords.get("title").literal | default("Zarf Package Schema") | md_heading(depth) }}
+{{ schema.keywords.get("title").literal | default("Zarf Package Schema") | md_heading(0) }}
 {% set contentBase %}
-{% with schema=schema, skip_headers=False, depth=depth %}
+{% with schema=schema, skip_headers=False %}
     {% include "content.md" %}
 {% endwith %}
 {% endset %}

hack/zarf-jsfh-template/content.md → docs/.templates/jsonschemaforhumans/content.md

@@ -8,7 +8,6 @@
 #}
 {# context parameters default values #}
 {% set skip_headers = skip_headers or False %}
-{% set depth = depth or 0 %}
 {# end context parameters #}
 
 {% set keys = schema.keywords %}
@@ -27,7 +26,7 @@
 
 {% if schema.should_be_a_link(config) %}
 {% elif schema.refers_to -%}
-    {%- with schema=schema.refers_to_merged, skip_headers=True, depth=depth -%}
+    {%- with schema=schema.refers_to_merged, skip_headers=True -%}
         {% include "content.md" %}
     {% endwith %}
 {% else %}
@@ -62,7 +61,7 @@
 
     {# Conditional subschema, or if-then-else section #}
     {% if schema.has_conditional %}
-        {% with skip_headers=False, depth=depth+1 %}
+        {% with skip_headers=False %}
             {% include "section_conditional_subschema.md" %}
         {% endwith %}
     {% endif %}

docs/.templates/jsonschemaforhumans/section_array.md

@@ -0,0 +1,36 @@
+{% set min_items = schema.kw_min_items.literal or "N/A" %}
+{% set max_items = schema.kw_max_items.literal or "N/A" %}
+{% set kw_unique_items = schema.kw_unique_items.literal or "False" %}
+{% set kw_additional_items = schema.kw_additional_items.literal or "N/A" %}
+
+{{ md_badge("Min Items: " + min_items, "gold", show_text=False) }}
+{{ md_badge("Max Items: " + max_items, "gold", show_text=False) }}
+{{ md_badge("Item unicity: " + kw_unique_items, "gold", show_text=False) }}
+{{ md_badge("Additional items: " + kw_additional_items, "gold", show_text=False) }}
+
+
+{% if schema.array_items_def %} {% filter md_heading(2) %} {% with schema=schema.array_items_def %}{%- include "breadcrumbs.md" %}{% endwith %} {% endfilter %} {% with schema=schema.array_items_def, skip_headers=False, skip_required=True %} {% include "content.md" %} {% endwith %} {% endif %}
+
+{% if schema.kw_items %}
+{{ md_badge("Min Items: " + min_items, "gold", show_text=False) }}
+{{ md_badge("Max Items: " + max_items, "gold", show_text=False) }}
+{{ md_badge("Item unicity: " + kw_unique_items, "gold", show_text=False) }}
+{{ md_badge("Additional items: " + kw_additional_items, "gold", show_text=False) }}
+
+
+{% for item in schema.kw_items %}
+    {% filter md_heading(3, item.html_id) %}
+    {% with schema=item %}{%- include "breadcrumbs.md" %}{% endwith %}
+    {% endfilter %}
+    {% with schema=item, skip_headers=False, skip_required=True %}
+        {% include "content.md" %}
+    {% endwith %}
+{% endfor %}
+{% endif %}
+
+{% if schema.kw_contains and schema.kw_contains.literal != {} %}
+{{ "At least one of the items must be" | md_heading(3) }}
+{% with schema=schema.kw_contains, skip_headers=False, skip_required=True %}
+    {% include "content.md" %}
+{% endwith %}
+{% endif %}

hack/zarf-jsfh-template/section_conditional_subschema.md → docs/.templates/jsonschemaforhumans/section_conditional_subschema.md

@@ -2,22 +2,22 @@
     {% set first_property =  schema.kw_if | get_first_property %}
 
     {% if schema.kw_then %}
-        {%- filter md_heading(depth) -%}If (
+        {%- filter md_heading(2) -%}If (
             {{- first_property.property_name | md_escape_for_table -}}
             {{- " = " -}}
             {{- first_property.kw_const.literal | python_to_json -}}
         ){%- endfilter -%}
-        {% with schema=schema.kw_then, skip_headers=False, depth=depth %}
+        {% with schema=schema.kw_then, skip_headers=False%}
             {% include "content.md" %}
         {% endwith %}
     {% endif %}
     {% if schema.kw_else %}
-        {%- filter md_heading(depth) -%}Else (i.e. {{ " " }}
+        {%- filter md_heading(2) -%}Else (i.e. {{ " " }}
             {{- first_property.property_name | md_escape_for_table -}}
             {{- " != " -}}
             {{- first_property.kw_const.literal | python_to_json -}}
         ){%- endfilter -%}
-        {% with schema=schema.kw_else, skip_headers=False, depth=depth %}
+        {% with schema=schema.kw_else, skip_headers=False %}
             {% include "content.md" %}
         {% endwith %}
     {% endif %}

hack/zarf-jsfh-template/section_examples.md → docs/.templates/jsonschemaforhumans/section_examples.md

@@ -1,8 +1,8 @@
 **Example{% if examples|length > 1 %}s{% endif %}:**{{ " " }}
 
+<code>
 {% for example in examples %}
 {% set example_id = schema.html_id ~ "_ex" ~ loop.index %}
-```json
-{{ example }}
-```
+{{ example }}{%- if not loop.last %}, {% endif -%}
 {% endfor %}
+</code>

docs/.templates/jsonschemaforhumans/section_not.md

@@ -0,0 +1,4 @@
+{{ "Must **not** be" | md_heading(3) }}
+{% with schema=schema.kw_not, skip_headers=False, skip_required=True %}
+    {% include "content.md" %}
+{% endwith %}

docs/.templates/jsonschemaforhumans/section_properties_details.md

@@ -0,0 +1,57 @@
+{% for sub_property in schema.iterate_properties %}
+  {%- if sub_property.is_additional_properties and not sub_property.is_additional_properties_schema -%}
+    {% continue %}
+  {% endif %}
+
+  {% set html_id = sub_property.html_id %}
+
+  {% set description = sub_property | get_description %}
+
+{% if sub_property.type_name == "object" or sub_property.type_name == "array" %}
+<details open>
+{% else %}
+<details>
+{% endif %}
+<summary>
+    {% filter md_heading(1, html_id, True) -%}
+      {%- filter replace('\n', '') -%}
+        {%- if sub_property is deprecated  -%}~~{%- endif -%}
+        {%- if sub_property.is_pattern_property %} Pattern Property{% endif %} {% with schema=sub_property %}{%- include "breadcrumbs.md" %} {% endwith %}
+        {%- if not skip_required and sub_property.property_name -%}
+            {{ "*" if sub_property.is_required_property else "" -}}
+        {%- endif -%}
+        {%- if sub_property is deprecated -%}~~{%- endif -%}
+      {%- endfilter %}
+    {%- endfilter %}
+
+</summary>
+&nbsp;
+<blockquote>
+
+  {% if sub_property.type_name == "object" or sub_property.type_name == "array" %}
+  ## {% with schema=sub_property %}
+    {%- for node in schema.nodes_from_root -%}
+      {%- if node.name_for_breadcrumbs == "root" or node.name_for_breadcrumbs.endswith(" items") -%}{% continue %}{%- endif -%}
+      {{ node.name_for_breadcrumbs }}{%- if not loop.last %} > {% endif -%}
+    {%- endfor -%}
+  {% endwith %}
+  {% endif %}
+
+  {% with schema=sub_property, skip_headers=False %}
+    {% if sub_property.is_pattern_property %}
+:::note
+All properties whose name matches the regular expression
+```{{ sub_property.property_name }}``` ([Test](https://regex101.com/?regex={{ sub_property.property_name | urlencode }}))
+must respect the following conditions
+:::
+    {% endif %}
+    {%- if not skip_required and sub_property.property_name -%}
+        {{ md_badge("Required", "red", show_text=False) if sub_property.is_required_property else "" -}}
+    {%- endif -%}
+    {% include "content.md" %}
+  {% endwith %}
+
+</blockquote>
+</details>
+
+{% endfor %}

hack/zarf-jsfh-template/section_undocumented_required_properties.md → docs/.templates/jsonschemaforhumans/section_undocumented_required_properties.md

@@ -1,6 +1,6 @@
 {% set undocumented_required_properties = schema | get_undocumented_required_properties %}
 {% if undocumented_required_properties%}
-{{ "The following properties are required" | md_heading(depth+1) }}
+{{ "The following properties are required" | md_heading(3) }}
 {% for required_property in undocumented_required_properties %}
 * {{ required_property }}
 {% endfor %}

hack/zarf-jsfh-template/tabbed_section.md → docs/.templates/jsonschemaforhumans/tabbed_section.md

@@ -5,11 +5,11 @@
 {% for node in current_node.array_items %}
 <blockquote>
 
-    {% filter md_heading(depth+1, node.html_id) -%}
+    {% filter md_heading(2, node.html_id) -%}
         {% if node.is_pattern_property %}Pattern{% endif %} Property `{% with schema=node %}{%- include "breadcrumbs.md" %}{% endwith %}`
     {%- endfilter %}
 
-    {% with schema=node, skip_headers=False, depth=depth+1 %}
+    {% with schema=node, skip_headers=False %}
         {% include "content.md" %}
     {% endwith %}