nebari-dev / nebari-dev/nebari-docs
Reference docs: Auto-generated nic CLI, config schema, and NicApp CRD
Open
@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 incmd/nic/) - Generation: Cobra's built-in doc generator (
cobra.GenMarkdownTree), emitted by amake docstarget 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/andpkg/provider/*/config.goinnebari-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-docspulls generated markdown at build time (git submodule, released artifact, ornpm run docs:syncscript: 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)
-
NicAppCRD reference is generated from the CRD (no hand-edited schema) - Generation runs in CI and drift is caught automatically
Reference
Repos:
nicCLI: 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/
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.