ci(docs): generate the Kubernetes API reference at publish time - #14122
ci(docs): generate the Kubernetes API reference at publish time#14122dagil-nvidia wants to merge 3 commits into
Conversation
The publish job ran `gen_kubernetes_api.py --check` before the sync steps, so a stale committed page failed the step and skipped both the sync and `fern generate --docs`. The site stopped updating and nothing said so. The per-PR gate is `--since`-scoped, which is correct: a branch should only fail for drift it caused. But that leaves merge skew uncovered. A PR that regenerates against main at T1 merges at T3 after a second PR edited the generator's source at T2, and neither PR is at fault. Main is stale and the next publish is the thing that breaks. Regenerate instead of checking. The generator's only input is the docs-owned `api-reference-k8s.md` in the same checkout, and generation already precedes the `pages-dev` rsync, so the fresh output publishes. This is the pattern #13556 established for the Python and Rust references; the Kubernetes page differs only in staying committed, which it still does. The scoped pre-merge gate is unchanged and still keeps the committed copy honest for reviewers. Validation: - Corrupted the committed page: `--check` fails, write mode restores byte-identical output, `--check` is clean again. - `gen_kubernetes_api.py --check` clean on a pristine tree. - fern-docs.yml parses; check_action_pins.py passes. Signed-off-by: Dan Gil <dagil@nvidia.com>
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 009de8e23c
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
![dynamo-review-agent[bot]](https://avatars.githubusercontent.com/u/201626793?s=60&v=4){kind=small}
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Enterprise Run ID: 📒 Files selected for processing (1)
Included review availability: Your plan provides up to 12 included reviews per hour; 11 remain after this review. WalkthroughThe documentation workflow now generates Kubernetes API references in write mode. It includes the regenerated output in the synchronization and publication flow. ChangesKubernetes documentation publication
Estimated code review effort: 2 (Simple) | ~10 minutes Merge Risk: ⚪ Minimal · up to The publish workflow now regenerates the Kubernetes API reference before synchronization, preventing stale committed output from blocking documentation updates; no actionable merge-blocking risk remains after normal checks and review. 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
Full details: Description checkExplanation The description explains the problem, implementation, scope, and validation. However, it does not use the required Overview, Details, or Where should the reviewer start sections, and it omits the required Related Issues selection. Resolution Add the required template sections. Include an Overview, Details, and specific reviewer starting points. Complete Related Issues by adding either the linked issue reference or the confirmation checkbox for no related issue, then remove the unused alternative path. Full details: Docstring CoverageExplanation No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0 files. (1 skipped: 1 unsupported.)
Comment |
Review caught that the first version removed a property the repository deliberately protects. The Kubernetes page is committed BECAUSE reviewers read it in the PR diff, and regenerating at publish meant the site could ship bytes that differed from the ones approved, with no signal. A regression test asserted the old `--check` for exactly that reason. Keep both properties instead of trading one for the other: - Publish regenerates, so merge skew on main can no longer fail the step and silently skip the sync and publish steps that follow it. The site is always current. - A probe records whether the committed copy differed, and a gate at the very end of the job fails the run when it did. The mismatch stays loud and attributable; it just no longer freezes docs.nvidia.com to report itself. The regression test now asserts the new contract against the step's parsed `run` body rather than the workflow text, so an assertion cannot pass on a comment that happens to name the same command. Validation: - Reverting the invocation to `--check` fails the test. - Deleting the post-publish gate fails the test. - The full test_api_reference_regressions.py file passes, 38 tests. - fern-docs.yml parses; the gate is the last step of the job and sorts after Publish Docs. Signed-off-by: Dan Gil <dagil@nvidia.com>
github-actions
Bot
added
the
documentation
|
/ok to test b2cdf31 |
Signed-off-by: Dan Gil <dagil@nvidia.com>
|
/ok to test a00428f |
1 participant
Summary
The docs publish job ran
gen_kubernetes_api.py --checkbefore its sync steps. A stalecommitted page therefore failed that step, which skipped both the
pages-devsync andfern generate --docs. The site stopped updating and nothing announced it.The per-PR gate in
pre-merge.ymlis--since-scoped, which is correct: a branch shouldonly fail for drift it caused. But that leaves merge skew uncovered. A PR that regenerates
against
mainat T1 merges at T3 after a second PR edited the generator's source at T2.Neither PR is at fault,
mainis stale, and the next publish is the thing that breaks.This regenerates instead of checking. The generator's only input is the docs-owned
api-reference-k8s.mdpresent in the same checkout, and generation already precedes thepages-devrsync, so the fresh output publishes. That is the pattern#13556 established for the Python and Rust
references; the Kubernetes page differs only in staying committed, which it still does
because reviewers read it in the PR diff.
The
--since-scoped pre-merge gate is unchanged and still keeps the committed copy honestfor review. There is exactly one publish-blocking invocation in the repository, so this is
the only site that needed changing; the release-version job does not call this generator.
Validation
full-api-reference.mdx, then confirmed the sequence end to end:--checkfails (reproducing the publish block), write mode restores byte-identicaloutput, and
--checkis clean again.gen_kubernetes_api.py --checkclean on a pristine tree..github/workflows/fern-docs.ymlparses as YAML.scripts/check_action_pins.pypasses.Summary by CodeRabbit