Reference docs: nic CLI, config schema, NicApp CRD, personas (auto-generated from source)

[dcmcand]

Part of epic #621.

Goal

Provide precise, lookup-style reference material for NKP. Reference content must be auto-generated from the upstream source repos wherever possible so it cannot drift from the code. Hand-written reference is a fallback, not the norm.

Scope

New or rewritten pages under docs/docs/references/. For each: establish a generation pipeline that runs in CI (in this repo or upstream) and publishes the output into the site.

nic CLI reference — auto-generated

• Source: nebari-infrastructure-core (Cobra commands in cmd/nic/)
• Generation: Cobra's built-in doc generator (cobra.GenMarkdownTree), emitted by a make docs target upstream, pulled into this site at build
• Output: one page per command (deploy, destroy, kubeconfig, validate, version) with flags, args, env vars
• No hand-edited CLI pages in this repo

NIC configuration schema — auto-generated

• Source: Go struct tags across pkg/config/ and pkg/provider/*/config.go in nebari-infrastructure-core
• Generation: the existing plan under nebari-infrastructure-core/docs/plans/config-doc-generator/ — finish and wire it in
• Output: per-provider schema pages (AWS, Hetzner, GCP, Azure, local), DNS provider config (Cloudflare), runtime flags

NicApp CRD reference — auto-generated

• Source: CRD definition in nebari-dev/nebari-operator
• Generation: controller-gen / crd-ref-docs (or equivalent) producing markdown from the CRD schema
• Output: field-by-field reference, annotated examples

Personas — hand-written (the only non-generated piece)

• Rewrite docs/docs/references/personas.md for NKP:
  • Platform admin — provisions clusters, manages foundational software, installs packs
  • Pack developer — builds/packages/publishes capabilities
  • End user — consumes the landing page and deployed capabilities

Pipeline requirements

• Generators live in the upstream repos (nebari-infrastructure-core, nebari-operator), not this repo
• nebari-docs pulls generated markdown at build time (git submodule, released artifact, or npm run docs:sync script — pick the simplest that works)
• CI in the upstream repos fails the build if generators error
• This repo's build fails if generated content is missing or stale beyond a pinned version

Out of scope

• Conceptual explanations (separate sub-issues)
• How-tos (separate sub-issues)
• Per-pack reference (packs own their own docs)

Acceptance criteria

• CLI reference is generated from nebari-infrastructure-core — no hand-edited CLI pages
• Config schema is generated from struct tags — no hand-edited field lists
• NicApp CRD reference is generated from the CRD — no hand-edited schema
• Personas page rewritten around NKP roles
• Generation runs in CI and drift is caught automatically

Reference

Repos:

• nic CLI: https://github.com/nebari-dev/nebari-infrastructure-core
• Nebari Operator: https://github.com/nebari-dev/nebari-operator

Source in nebari-infrastructure-core:

• Existing CLI reference: docs/cli-reference.md
• Config design: docs/design-doc/implementation/07-configuration-design.md
• Config types: pkg/config/config.go, pkg/provider/*/config.go
• Config doc generator plan: docs/plans/config-doc-generator/
• Examples: examples/

Notes for dev rel decomposition

Likely sub-tasks: (a) CLI generator upstream + sync, (b) config generator upstream + sync, (c) CRD generator upstream + sync, (d) personas rewrite, (e) drift-detection CI. Coordinate with upstream maintainers for (a)–(c).