docs: add the docs site publishing to packs.nebari.dev#41
Merged
Conversation
Adds an Astro/Starlight docs site under docs/site, using the shared @nebari/starlight theme (matching the wiring in software-pack-dashboard), with content seeded from the README, Makefile, chart values, and CI workflows: quickstart, installation, local development, troubleshooting, configuration, architecture, and CI/CD and releasing. SITE and BASE come from env, matching nebari-llm-serving-pack's pattern, so the same build works locally (BASE=/) and in production (SITE=https://packs.nebari.dev BASE=/nebari-frames/). A small remark plugin prefixes root-absolute content links with BASE so they still resolve once deployed under a subpath. The header's GitHub link is overridden to point at this repo instead of the shared theme's default org-level link. Also adds .github/workflows/docs.yml to build and deploy the site to Cloudflare Pages on push to main and on pull requests, modeled on nebari-llm-serving-pack's docs workflow (without the Playwright/mermaid and link-check steps this project has no use for).
Adds tools/docs-gen, which walks the frames CLI's cobra command tree (cli/cmd.NewRootCmd) with spf13/cobra/doc and writes one Starlight-ready Markdown page per command into docs/site/src/content/docs/reference/cli. Output is deterministic (auto-gen-tag disabled) and committed, so the docs site builds without needing Go. go.mod/go.sum pick up spf13/cobra/doc's own dependency (go-md2man), which was not previously pulled in since nothing imported the doc subpackage. Run `go run ./tools/docs-gen` from the repository root to regenerate after CLI changes.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this is
Adds the Nebari Frames docs site: an Astro + Starlight site under
docs/site, built on the shared@nebari/starlighttheme (matching the wiring insoftware-pack-dashboard) so it looks and behaves like the rest of the Nebari Software Packs docs.Content is seeded from the repo itself, not written from scratch: the README, Makefile comments,
chart/values.yaml, and the.github/workflows/*.ymlfiles. It covers publishing and browsing a Frame with the CLI, installing on a Nebari cluster (prerequisites, thenebari.dev/managednamespace label, the three auth modes, NebariApp integration, an ArgoCD pointer), the two local dev loops, a values reference organized by area, the architecture and auth flow, CI/CD and how to cut a release, and troubleshooting for the two OIDC-provisioning failure modes an operator is most likely to hit.Layout
Pagefind search and the light/dark theme toggle are Starlight defaults and are left enabled. The header's GitHub link points at this repo; the shared theme plugin always adds its own org-level GitHub link first, so the header's
SocialIconscomponent is overridden to drop that default once a repo-specific link is configured (see the comment indocs/site/astro.config.mjs).CLI reference (generated)
tools/docs-genwalks theframesCLI's cobra command tree (cli/cmd.NewRootCmd) withspf13/cobra/docand writes one Markdown page per command intodocs/site/src/content/docs/reference/cli, with Starlight frontmatter added sincecobra/docdoes not produce any. Output is deterministic (cobra's date-stamped auto-gen footer is disabled) and is committed, so the site builds without needing Go. Regenerate after CLI changes withgo run ./tools/docs-genfrom the repo root, then commit the result.Deploy mechanics
.github/workflows/docs.ymlbuilds the site and deploys it to Cloudflare Pages, modeled onnebari-llm-serving-pack's docs workflow (its Playwright/mermaid and link-check steps are omitted since this project has neither):mainand on pull requests touchingdocs/**,tools/docs-gen/**, or the workflow file.SITE/BASEare computed per ref:mainbuilds forhttps://packs.nebari.devat/nebari-frames/; PR builds use a per-branch Pages alias at/.cloudflare/wrangler-action@v3to thenebari-framesPages project, skipped for fork PRs (no secret access), with a PR comment linking the preview.Verification
npm ci && SITE=https://packs.nebari.dev BASE=/nebari-frames/ npm run buildsucceeds;dist/containspagefind/and all expected pages.go run ./tools/docs-genrun twice in a row produces no diff.go build ./...,go vet ./..., andgolangci-lint runare clean.actionlinton.github/workflows/docs.ymlexits 0.Ops checklist (not in this PR)
CLOUDFLARE_API_TOKENandCLOUDFLARE_ACCOUNT_IDrepository secrets. The workflow's build and lint gates run without them; only the deploy step needs them.docs_site: trueinpack-metadata.yamland updatelinks.docstohttps://packs.nebari.dev/nebari-frames/, matching the convention innebari-llm-serving-pack.Closes #24, part of #35.