nebari-dev / nebari-dev/nebari-docs

Reference docs: Auto-generated nic CLI, config schema, and NicApp CRD

Open
#665 1 comment 0 reactions 1 assignee View on GitHub

@andrewfulton9 is already working on this.

Since Jun 23, 2026.

area: documentation 📖 nkp-migration
Dominant language
No language data
Stars
21
Forks
40
Avg merge
19h 50m
Merged PRs (30d)
6

Description

Sub-issue of #632.

Scope

Auto-generated reference content under docs/docs/references/ for the three sources of structured truth: nic CLI, NIC config schema, and the NicApp CRD. Generators live in upstream repos; this site pulls the generated markdown at build time. Reference content must be auto-generated wherever possible so it cannot drift from the code.

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

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

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)
  • Generation runs in CI and drift is caught automatically

Reference

Repos:

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/

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.