docs(ci): generate releases.json and atom feed at publish time - #13344
Merged
Conversation
Collaborator
Author
|
/ok to test 51ed56e |
github-actions
Bot
added
docs
documentation
Contributor
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
![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: 51ed56ef29
ℹ️ 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}
Collaborator
Author
|
/ok to test 16adb53 |
|
🔄 Datadog auto-retried 2 jobs - 1 passed on retry 🎯 Code Coverage (details) 🔗 Commit SHA: 8778569 | Docs | Datadog PR Page | Give us feedback! |
dagil-nvidia
force-pushed
the
dagil/docs-gen-publish-time
branch
from
August 17, 2026 03:11
16adb53 to
72cf8da
Compare
Collaborator
Author
|
/ok to test 72cf8da |
Collaborator
Author
|
/ok to test 0662c59 |
dagil-nvidia
force-pushed
the
dagil/docs-gen-determinism
branch
from
August 17, 2026 12:35
4c621ce to
8b083dc
Compare
dagil-nvidia
force-pushed
the
dagil/docs-gen-publish-time
branch
from
August 17, 2026 14:59
0662c59 to
f187b28
Compare
Collaborator
Author
|
/ok to test f187b28 |
BenHamm
approved these changes
Aug 17, 2026
BenHamm
left a comment
BenHamm
left a comment
Contributor
There was a problem hiding this comment.
Docs stamp for the v1.4.0 follow-ups.
releases.json and releases-atom.xml are whole-file rewrites of one committed source (releases.data.ts), and any two PRs that regenerated them merge-conflicted on the entire file body even when their source edits did not overlap. With generator determinism proven in CI by the previous commit, stop committing them: - fern-docs.yml generates both assets fail-closed right before the assets sync: exist and non-empty, JSON parses with a non-empty releases array, entry count non-decreasing versus the previously published copy, latest version matches CURRENT_VERSION in releases.data.ts. - gen_llms_tables.py gains --assets-only (publish path; never mutates pages) and narrows --check to the marker-spliced pages, which stay committed for review. - Both assets are deleted from git and gitignored; the pre-commit freshness hook and check_reference.sh drop their asset patterns; simulate_docs_website.sh mirrors the publish-time generate step. - docs/fern/AGENTS.md records the decision rule for future generated files (commit vs publish-time vs post-merge regeneration). - releases-machine-readable.mdx and release-history.mdx point consumers at the canonical published URLs. Signed-off-by: Dan Gil <dagil@nvidia.com>
…cks to main publishes Review findings on the publish-time generation step: - RELEASES may be headed by a platform-preview or model-build entry while CURRENT_VERSION stays on the prior stable (v1.1.0-dev.*, v1.3.0-dev.1 precedent; components resolve with .find(), never [0]). Assert membership instead of position so preview windows cannot fail-close every docs publish. - The entry-count regression check compares against the live published copy, which a preview build lagging main would trip; run it only when IS_MAIN is true. - Skip generation gracefully on preview source trees that predate the generator; still fail-closed on main. - Note in release-version that the tag job serves whatever assets the last main-sync generated. Signed-off-by: Dan Gil <dagil@nvidia.com>
…se assets Review findings on the publish-time generation step: - Previews of maintained branches whose gen_llms_tables.py predates --assets-only (or is absent) failed the step before Fern could build. Detect flag support via --help; skip generation on unsupported non-main sources while still syncing their committed assets. Main stays fail-closed. - The synced fern/.gitignore ignores the generated assets on docs-website, so a bootstrap copy (file absent there) would be skipped by the commit step's git add -A and the published raw URL would 404 permanently. Force-add both files after the sync. Signed-off-by: Dan Gil <dagil@nvidia.com>
Collaborator
Author
|
/ok to test 8778569 |
Collaborator
Author
|
/ok to test 8778569 |
dagil-nvidia
force-pushed
the
dagil/docs-gen-publish-time
branch
from
August 17, 2026 18:08
f187b28 to
8778569
Compare
Collaborator
Author
|
/ok to test 8778569 |
sara4dev
approved these changes
Aug 17, 2026
dagil-nvidia
added a commit
that referenced
this pull request
Aug 19, 2026
The Python/Rust API reference pages are deterministic outputs of gen_python_api.py / gen_rust_api.py over the source tree. Committing them meant every source PR touching a documented symbol had to carry the regenerated MDX (the pre-merge freshness gate required it) and wait on docs codeowner review for a diff no human authored. Follow the releases.json/atom precedent (#13344): delete the committed pages, gitignore their directories (anchored at /pages/ so the synced .gitignore on docs-website cannot swallow the published snapshots), and generate at publish time instead: - fern-docs.yml preview/publish: generate both references against the exact ref being published, before the pages-dev rsync. - fern-docs.yml version tags: generate from the tagged source, skipping (never failing) older tags that still commit their pages. - pre-merge: run both generators in write mode so a source PR that breaks generation still fails fast; the fern-check job materializes the pages before fern check validates the nav. - The Kubernetes reference regenerates from a committed docs-side file, so it stays committed and keeps its --since-scoped freshness gate. Tests that diffed rendered output against the shipped tree now assert against a fresh render; suite is 205 passing. Signed-off-by: Dan Gil <dagil@nvidia.com>
This was referenced Aug 19, 2026
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
3 participants
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.
Summary
Stacked on #13338 (retargets to
mainautomatically when it merges). Second half of the generated-docs conflict-reduction plan.releases.json(~2100 lines) andreleases-atom.xmlare whole-file rewrites of one committed source,releases.data.ts. During v1.4.0 they merge-conflicted PR pairs whose source edits did not overlap, costing a rebase + regenerate + full re-CI cycle each time. With determinism proven in CI by #13338, this PR stops committing them:fern-docs.ymlgenerates both assets fail-closed immediately before the assets sync: exist and non-empty, JSON parses with a non-empty releases array, entry count non-decreasing versus the previously published copy ondocs-website,CURRENT_VERSIONfromreleases.data.tspresent in the generated data (membership, not position: the array may be headed by a platform-preview or model-build entry). The progression checks run only on main publishes, so preview builds lagging main cannot trip them.gen_llms_tables.pygains--assets-only(the publish path; never mutates pages) and narrows--checkto the five marker-spliced pages, which stay committed for review.check_reference.shdrop their asset patterns;simulate_docs_website.shmirrors the publish-time generate step.docs/fern/AGENTS.mdrecords the decision rule for future generated files (commit vs publish-time vs post-merge regeneration).releases-machine-readable.mdxandrelease-history.mdxpoint consumers at thedocs-websitebranch raw URLs (verified 200), which the publish pipeline regenerates on every docs publish.Validation
gen_llms_tables.py --checkexits 0 with both assets absent;--assets-onlywrites exactly the two assets and touches no page.CURRENT_VERSION= v1.4.0,releases[0].version= v1.4.0, 29 entries.pre-commit runpasses on all eleven touched files, including the generator's unit suite and the narrowed freshness hook.🤖 Generated with Claude Code