generate docs from zarf schema json (#614)

.github/workflows/zarf-schema-check.yml

@@ -0,0 +1,37 @@
+name: zarf-schema-check
+on:
+  pull_request:
+    paths:
+      - "src/types/**"
+      - "zarf.schema.json"
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: "Install GoLang"
+        uses: actions/setup-go@v3
+        with:
+          go-version: 1.18.x
+
+      - name: "Checkout Repo"
+        uses: actions/checkout@v3
+
+      - name: "Setup caching"
+        uses: actions/cache@v3
+        with:
+          path: |
+            ~/.cache/go-build
+            ~/go/pkg/mod
+          key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
+          restore-keys: |
+            ${{ runner.os }}-go-
+
+      - name: "Backup Repo Schema Version"
+        run: 'cp zarf.schema.json zarf.schema.json.bak'
+
+      - name: "Regenerate Schema"
+        run: 'go run main.go tools config-schema > zarf.schema.json'
+
+      - name: "Compare Schemas"
+        run: 'cmp -s zarf.schema.json zarf.schema.json.bak'

.hooks/jsfh-config.json

@@ -0,0 +1,6 @@
+{
+  "custom_template_path": ".hooks/zarf-jsfh-template/base.md",
+  "template_md_options": { "badge_as_image": true, "show_heading_numbers": false },
+  "show_toc": false,
+  "show_breadcrumbs": false
+}

.hooks/verify-zarf-schema.sh

@@ -1,2 +1,3 @@
 #!/usr/bin/env sh
 go run main.go tools config-schema > zarf.schema.json
+docker run -it -v $(pwd):/app -w /app --rm python:3.8-alpine /bin/sh -c "pip install json-schema-for-humans && generate-schema-doc --config-file .hooks/jsfh-config.json zarf.schema.json docs/4-user-guide/3-zarf-schema.md"

.hooks/zarf-jsfh-template/base.md

@@ -0,0 +1,16 @@
+{% set depth = 0 %}
+{{ schema.keywords.get("title").literal | default("Zarf Package Schema") | md_heading(depth) }}
+{% set contentBase %}
+{% with schema=schema, skip_headers=False, depth=depth %}
+    {% include "content.md" %}
+{% endwith %}
+{% endset %}
+
+{{ md_get_toc() }}
+
+{{ contentBase }}
+
+----------------------------------------------------------------------------------------------------------------------------
+{% if config.with_footer -%}
+Generated from [zarf.schema.json](https://github.com/defenseunicorns/zarf/blob/master/zarf.schema.json){% if config.footer_show_time %} on {{ get_local_time() }}{% endif %}
+{%- endif -%}

.hooks/zarf-jsfh-template/breadcrumbs.md

@@ -0,0 +1,9 @@
+{% filter md_escape_for_table %}
+{%- if config.show_breadcrumbs %}
+  {%- for node in schema.nodes_from_root -%}
+    {{ node.name_for_breadcrumbs }}{%- if not loop.last %} > {% endif -%}
+  {%- endfor -%}
+{%- else -%}
+  {{- schema.name_for_breadcrumbs or schema.property_name -}}
+{% endif %}
+{% endfilter %}

.hooks/zarf-jsfh-template/content.md

@@ -0,0 +1,93 @@
+{#
+    content is a template and not a macro in md
+        because macro parameters are not through context
+        when rendering a template from the macro and it caused
+        serious problems when using recursive calls
+    mandatory context parameters:
+    schema
+#}
+{# context parameters default values #}
+{% set skip_headers = skip_headers or False %}
+{% set depth = depth or 0 %}
+{# end context parameters #}
+
+{% set keys = schema.keywords %}
+{%- if not skip_headers %}
+
+{% if schema.title and schema.title | length > 0 %}
+**Title:** {{ schema.title }}
+{% endif %}
+
+{% set description = (schema | get_description) %}
+{% include "section_description.md" %}
+
+{{ schema | md_type_info_table | md_generate_table }}
+
+{% endif %}
+
+{% if schema.should_be_a_link(config) %}
+{% elif schema.refers_to -%}
+    {%- with schema=schema.refers_to_merged, skip_headers=True, depth=depth -%}
+        {% include "content.md" %}
+    {% endwith %}
+{% else %}
+
+    {# Combining: allOf, anyOf, oneOf, not #}
+    {% if schema.kw_all_of %}
+        {% with operator="allOf", title="All of(Requirement)", current_node=schema.kw_all_of, skip_required=True %}
+            {% include "tabbed_section.md" %}
+        {% endwith %}
+    {% endif %}
+    {% if schema.kw_any_of %}
+        {% with operator="anyOf", title="Any of(Option)", current_node=schema.kw_any_of, skip_required=True %}
+            {% include "tabbed_section.md" %}
+        {% endwith %}
+    {% endif %}
+    {% if schema.kw_one_of %}
+        {% with operator="oneOf", title="One of(Option)",current_node=schema.kw_one_of, skip_required=True %}
+            {% include "tabbed_section.md" %}
+        {% endwith %}
+    {% endif %}
+    {% if schema.kw_not %}
+        {% include "section_not.md" %}
+    {% endif %}
+
+    {# Enum and const #}
+    {% if schema.kw_enum -%}
+        {% include "section_one_of.md" %}
+    {%- endif %}
+    {%- if schema.kw_const -%}
+        Specific value: `{{ schema.kw_const.raw | python_to_json }}`
+    {%- endif -%}
+
+    {# Conditional subschema, or if-then-else section #}
+    {% if schema.has_conditional %}
+        {% with skip_headers=False, depth=depth+1 %}
+            {% include "section_conditional_subschema.md" %}
+        {% endwith %}
+    {% endif %}
+
+    {# Required properties that are not defined under "properties". They will only be listed #}
+    {% include "section_undocumented_required_properties.md" %}
+
+    {# Show the requested type(s) #}
+    {{- schema | md_restrictions_table | md_generate_table -}}
+
+    {# Show array restrictions #}
+    {% if schema.type_name.startswith("array") %}
+        {% include "section_array.md" %}
+    {% endif %}
+
+    {# Display examples #}
+    {% set examples = schema.examples %}
+    {% if examples %}
+        {% include "section_examples.md" %}
+    {% endif %}
+
+    {# details of Properties, pattern properties, additional properties #}
+    {% if schema.type_name == "object" %}
+    {% with skip_required=False %}
+        {% include "section_properties_details.md" %}
+    {% endwith %}
+    {% endif %}
+{% endif %}

.hooks/zarf-jsfh-template/section_array.md

@@ -0,0 +1,23 @@
+{{ schema | md_array_restrictions | md_generate_table }}
+
+{% if schema.array_items_def %} {% filter md_heading(depth+1) %} {% 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 %}
+{{ schema | md_array_items_restrictions | md_generate_table }}
+
+{% for item in schema.kw_items %}
+    {% filter md_heading(depth+1, 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(depth+1) }}
+{% with schema=schema.kw_contains, skip_headers=False, skip_required=True %}
+    {% include "content.md" %}
+{% endwith %}
+{% endif %}

.hooks/zarf-jsfh-template/section_conditional_subschema.md

@@ -0,0 +1,24 @@
+{% if schema.kw_if %}
+    {% set first_property =  schema.kw_if | get_first_property %}
+
+    {% if schema.kw_then %}
+        {%- filter md_heading(depth) -%}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 %}
+            {% include "content.md" %}
+        {% endwith %}
+    {% endif %}
+    {% if schema.kw_else %}
+        {%- filter md_heading(depth) -%}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 %}
+            {% include "content.md" %}
+        {% endwith %}
+    {% endif %}
+{% endif %}

.hooks/zarf-jsfh-template/section_description.md

@@ -0,0 +1,4 @@
+{# Display description #}
+{% if description %}
+**Description:**{{ " " }}{{ description }}
+{% endif %}

.hooks/zarf-jsfh-template/section_examples.md

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

.hooks/zarf-jsfh-template/section_not.md

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

.hooks/zarf-jsfh-template/section_one_of.md

@@ -0,0 +1,6 @@
+:::note
+Must be one of:
+{% for enum_choice in schema.kw_enum.array_items %}
+* {{ enum_choice.literal | python_to_json }}
+{% endfor %}
+:::

.hooks/zarf-jsfh-template/section_properties_details.md

@@ -0,0 +1,43 @@
+{% 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 %}
+<details>
+<summary>{% filter md_heading(depth + 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>
+
+  {% 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 %}

.hooks/zarf-jsfh-template/section_undocumented_required_properties.md

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

.hooks/zarf-jsfh-template/tabbed_section.md

@@ -0,0 +1,19 @@
+<blockquote>
+
+{{ current_node | md_array_items(title) | md_generate_table }}
+
+{% for node in current_node.array_items %}
+<blockquote>
+
+    {% filter md_heading(depth+1, 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 %}
+        {% include "content.md" %}
+    {% endwith %}
+
+</blockquote>
+{% endfor %}
+
+</blockquote>

docs/4-user-guide/2-zarf-packages/1-zarf-packages.md

@@ -62,16 +62,7 @@ When Zarf is deploying the package, it will use the infrastructure that was crea
 
 ## What Makes Up A Package
 
-Zarf packages are split into smaller chunks called 'components'. These components are defined more in the [Zarf Components page](./2-zarf-components.md) but a quick way to understand components are as the actual named capabilities that packages provide. The schema of a zarf.yaml package follows the following format:
-
-```yaml
-kind: <STRING> # Either ZarfPackageConfig or ZarfInitConfig
-metadata:
-  name: <STRING> # The name of the package
-  description: <STRING> # A description of the package
-seed: <STRING> # Docker registry to seed the cluster with. Only used for init packages
-components: <OBJ LIST> # Components definitions are complex and broken down more in the 'Understanding Zarf Components' page
-```
+Zarf packages are split into smaller chunks called 'components'. These components are defined more in the [Zarf Components page](./2-zarf-components.md) but a quick way to understand components are as the actual named capabilities that packages provide. The schema of a zarf.yaml package is available here: [ZarfPackage Schema Docs](../3-zarf-schema.md)
 
 <br />
 <br />