troubleshoot/docs/preflight_docs.md

preflight docs

Extract and display documentation from a preflight spec

Synopsis

Extract all docString fields from enabled analyzers in one or more preflight YAML files. Templating is evaluated first using the provided values, so only documentation for analyzers that are enabled is emitted. The output is Markdown.

preflight docs [preflight-file...] [flags]

Examples

# Extract docs with defaults
preflight docs ml-platform-preflight.yaml

# Multiple specs with values files (later values override earlier ones)
preflight docs spec1.yaml spec2.yaml \
  --values values-base.yaml --values values-prod.yaml

# Inline overrides (Helm-style --set)
preflight docs ml-platform-preflight.yaml \
  --set monitoring.enabled=true --set ingress.enabled=false

# Save to file
preflight docs ml-platform-preflight.yaml -o requirements.md

Options

      --values stringArray   Path to YAML files containing template values (can be used multiple times)
      --set stringArray      Set template values on the command line (can be used multiple times)
  -o,  --output string       Output file (default: stdout)

Behavior

• Accepts one or more preflight specs; all are rendered, and their docStrings are concatenated in input order.
• Values merge: deep-merged left-to-right across --values files. --set overrides win last.
• Rendering engine:
  • If a spec references .Values, it is rendered with the Helm engine; otherwise Go text/template is used. A fallback to the legacy engine is applied for mixed templates.
• Map normalization: values maps are normalized to map[string]interface{} before applying --set to avoid type errors.
• Markdown formatting:
  • The first line starting with Title: in a docString becomes a Markdown heading.
  • If no Title: is present, the analyzer (or requirement) name is used.
  • Sections are separated by blank lines.

v1beta3 docString extraction

• v1beta3 layout uses spec.analyzers: [...].
• Each analyzer may include a sibling docString string.
• The docs command extracts spec.analyzers[*].docString after rendering.
• Backward compatibility: legacy requirements blocks are still supported and extracted when present.

SEE ALSO

• preflight - Run and retrieve preflight checks in a cluster