feat(docs): add cmd/docs schema emitter for docs.baseten.co#13
feat(docs): add cmd/docs schema emitter for docs.baseten.co#13pat-baseten wants to merge 1 commit into
Conversation
There was a problem hiding this comment.
Pull request overview
Adds a dedicated cmd/docs emitter and internal/docs library to generate a stable, versioned docs.json schema describing the Baseten CLI command tree for downstream documentation generation (e.g., docs.baseten.co), and wires it into CI + releases.
Changes:
- Introduce
internal/docsschema + walker to convertcmd.Rootinto a versioned JSON document, with unit tests and a golden snapshot. - Add
cmd/docsprogram to emitdocs.jsonwith reproducible timestamps viaSOURCE_DATE_EPOCH. - Update CI to smoke-test JSON emission, and update goreleaser to attach
docs.jsonto GitHub releases.
Reviewed changes
Copilot reviewed 9 out of 10 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
internal/docs/schema.go |
Defines the versioned JSON schema types for CLI docs emission. |
internal/docs/walk.go |
Implements tree-walking conversion from cmd.Command to the docs schema. |
internal/docs/schema_test.go |
Tests schema stability and JSON marshaling behavior. |
internal/docs/walk_test.go |
Unit tests for walker behavior (paths, flags, output, errors). |
internal/docs/golden_test.go |
Golden snapshot test against the real cmd.Root output. |
internal/docs/testdata/docs.golden.json |
Golden snapshot artifact used to detect drift in emitted schema. |
cmd/docs/main.go |
CLI entrypoint to emit docs.json to stdout or file with reproducible timestamps. |
cmd/docs/README.md |
Documents schema contract, versioning rules, and local usage/testing. |
.github/workflows/ci.yml |
Adds an Ubuntu-only smoke step to emit + parse-check docs.json. |
.goreleaser.yaml |
Generates docs.json during release and attaches it as a release asset. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| // GroupPri is the rendering priority for the flag's group (lower renders | ||
| // earlier). A value of 0 means the source field did not set group-pri; the | ||
| // group resolves to the framework default (DefaultFlagGroupPri = 100) at | ||
| // render time. Resolved by the walker — consumers should treat 0 as "use the | ||
| // framework default". |
| before: | ||
| hooks: | ||
| - go mod tidy | ||
| - sh -c 'go run ./cmd/docs --cli-version={{ .Version }} --out=docs.json' |
| before: | ||
| hooks: | ||
| - go mod tidy | ||
| - sh -c 'go run ./cmd/docs --cli-version={{ .Version }} --out=docs.json' |
There was a problem hiding this comment.
I do not think goreleaser needs to be running any of the docs stuff
There was a problem hiding this comment.
Can this move to internal/cmddocs to be less user facing? Running go run ./internal/cmddocs should be ok (and changing the other things in the package to be package main should be harmless for this kind of tool)
There was a problem hiding this comment.
Can this package be called cmddocs or docgen or similar? As docs/ it looks like actual docs
| - name: Emit docs.json (smoke) | ||
| if: matrix.os == 'ubuntu-latest' | ||
| run: | | ||
| go run ./cmd/docs --cli-version=ci --out=/tmp/docs.json | ||
| python3 -c "import json,sys; json.load(open('/tmp/docs.json')); print('valid JSON, $(wc -c < /tmp/docs.json) bytes')" |
There was a problem hiding this comment.
Can we have unit tests do the equivalent of this (run the code as Go, write to a temp dir, use Go to validate JSON, etc)
There was a problem hiding this comment.
Can you help me understand the purpose of this file? If this is something simply calling the code via a Go test can generate, why put it in the repo instead of generating it during the tests?
| if string(got) != string(want) { | ||
| t.Fatalf("docs.golden.json drift. If intentional, run:\n go test ./internal/docs -run Golden -update\n\nFirst 400 chars of got:\n%s", truncate(string(got), 400)) | ||
| } |
There was a problem hiding this comment.
I am not following this exactly. People have to keep some testdata/ up to date? See other comment on whether this is even needed
|
|
pat-baseten
force-pushed
the
docs-schema-emitter
branch
2 times, most recently
from
33cddf3 to
ff8d448
Compare
Walks the declarative cmd.Root tree and emits a versioned docs.json describing every command, flag, example, output shape, and typed error. Consumed by the docs.baseten.co pipeline, which pins a baseten-cli ref, runs `go run ./internal/cmddocs`, and generates the CLI reference. The emitter lives in internal/cmddocs (package main) so it is not a user-facing baseten subcommand. Release flow and goreleaser are untouched: the docs pipeline is the only caller.
pat-baseten
force-pushed
the
docs-schema-emitter
branch
from
ff8d448 to
0fd7271
Compare
cretz
left a comment
cretz
left a comment
There was a problem hiding this comment.
Nice and self-contained, looks great
Summary
Adds an
internal/cmddocsprogram that walks the declarativecmd.Roottree and emits a versioneddocs.jsondescribing every command, flag, example, output shape, and typed error. The schema inschema.gois the contract between this emitter anddocs.baseten.co;SchemaVersionis bumped only on breaking changes.The emitter lives in
internal/cmddocsaspackage main, so it is not a user-facingbasetensubcommand. Thedocs.baseten.copipeline pins a baseten-cli ref, runsgo run ./internal/cmddocs, and generates the CLI reference from the output — nothing in this repo's release flow runs the emitter or publishes the artifact.