docs(crds): 📝 generated+augmented Queue reference page (DOC-7 pilot)#91
Merged
Conversation
Establishes the per-CRD reference-doc pipeline (hybrid: generated field tables + hand-authored prose) and ships Queue as the pilot kind. - hack/tools/crd-ref-gen: deterministic generator that renders spec/status field tables from the v1beta1 CRD OpenAPI (config/crd/bases) into the <!-- crd-ref:begin KIND --> ... <!-- crd-ref:end --> blocks of docs/crds/*.md. Fields sorted for stable output; nested objects flattened one level; enums/maps/arrays rendered readably. - task docs:crd-ref regenerates the blocks; hack/verify.sh gates drift (regenerate-and-diff, consistent with controller-gen/mockery/samples). - docs/crds/queue.md: hand-authored intro, examples, and MQSC-mapping notes around the generated field tables; linked from crds/README.md and nav. - .gitignore: ignore a stray root crd-ref-gen binary (tool runs via go run). Remaining kinds (Topic, Channel, ChannelAuthRule, AuthorityRecord, QueueManagerConnection) follow per PR: add a page with markers, run the task. Approach chosen with the maintainer (generate + augment). Gates: verify OK (incl. new docs/crds drift check), lint OK, mkdocs build clean, markdownlint 0.
This was referenced Jul 10, 2026
konih
added a commit
that referenced
this pull request
Jul 10, 2026
…ot) (#91) Establishes the per-CRD reference-doc pipeline (hybrid: generated field tables + hand-authored prose) and ships Queue as the pilot kind. - hack/tools/crd-ref-gen: deterministic generator that renders spec/status field tables from the v1beta1 CRD OpenAPI (config/crd/bases) into the <!-- crd-ref:begin KIND --> ... <!-- crd-ref:end --> blocks of docs/crds/*.md. Fields sorted for stable output; nested objects flattened one level; enums/maps/arrays rendered readably. - task docs:crd-ref regenerates the blocks; hack/verify.sh gates drift (regenerate-and-diff, consistent with controller-gen/mockery/samples). - docs/crds/queue.md: hand-authored intro, examples, and MQSC-mapping notes around the generated field tables; linked from crds/README.md and nav. - .gitignore: ignore a stray root crd-ref-gen binary (tool runs via go run). Remaining kinds (Topic, Channel, ChannelAuthRule, AuthorityRecord, QueueManagerConnection) follow per PR: add a page with markers, run the task. Approach chosen with the maintainer (generate + augment). Gates: verify OK (incl. new docs/crds drift check), lint OK, mkdocs build clean, markdownlint 0.
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.
DOC-7 pilot — per-CRD reference docs (Queue)
Establishes the hybrid reference-doc pipeline (generated field tables + hand-authored prose) chosen with the maintainer, and ships Queue as the pilot kind. Remaining kinds follow per PR.
Pipeline
hack/tools/crd-ref-gen— deterministic Go generator. Reads thev1beta1CRD OpenAPI fromconfig/crd/bases/*.yamland rendersspec/statusfield tables (Field · Type · Required · Description) into the<!-- crd-ref:begin KIND -->…<!-- crd-ref:end -->blocks ofdocs/crds/*.md. Fields sorted (stable output); nested objects flattened one level (connectionRef.name); enums/maps/arrays rendered readably; descriptions pulled straight from the kubebuilder markers.task docs:crd-refregenerates the blocks.hack/verify.shgates drift (regenerate-and-diff, consistent with controller-gen / mockery / samples). Wired and proven:task verify→verify: ok.Content
docs/crds/queue.md— hand-authored intro, examples, and MQSC-mapping/drift notes around the generated tables. Linked fromcrds/README.mdand added to the mkdocs nav (Reference).Adding the next kind (recipe)
Add
docs/crds/<kind>.mdwith thecrd-ref:begin KIND/endmarkers + hand-authored prose, runtask docs:crd-ref, then add the nav entry + README link. One small PR per kind.Scope
Pilot only — Queue. Topic, Channel, ChannelAuthRule, AuthorityRecord, QueueManagerConnection remain (tracked as DOC-7 in-progress).
Gates
task verify✅ (includes the newdocs/crdsdrift check)task lint✅ (golangci-lint + go-arch-lint, 0 issues);task format✅mkdocs build✅ clean;--strictonly the pre-existing benign README/index noticemarkdownlint-cli2✅ 0 errorsgo.mod/go.sumchange (uses existingapiextensions+sigs.k8s.io/yamldeps); no generated-Go touched