fix(docs): populate fern version selector

[mckornfield]

Summary by CodeRabbit

• New Features

  • Added automatic generation of “frozen” Fern documentation snapshots for stable SemVer releases, including updated version navigation/version selection.

• Documentation

  • Updated Fern docs authoring/publishing guidance, clarified docs/fern/ layout, and added troubleshooting for missing release versions.

• Bug Fixes

  • Improved documentation publishing behavior to pull from the default branch with full history and refined tag triggering/eligibility checks for stable releases vs republish tags.

• Chores

  • Updated ignore rules for generated Fern outputs and versioned YAML artifacts.

[coderabbitai]

📝 Walkthrough

Walkthrough

Changes

Fern release documentation publishing

Layer / File(s)	Summary
Release tag discovery and CLI entrypoint docs/fern/scripts/materialize-release-versions.mjs, docs/fern/package.json	Adds SemVer tag discovery, eligibility checks, CLI flags, and the materialize:versions npm script with YAML support.
Snapshot generation and navigation update docs/fern/scripts/materialize-release-versions.mjs, docs/fern/scripts/sync-helm-docs.mjs	Extracts tagged docs, rewrites version paths, cleans generated artifacts, validates YAML, optionally generates Helm references, and updates docs.yml with generated release entries.
Publishing triggers and authoring guidance .github/workflows/publish-fern-docs.yaml, .gitignore, docs/AGENTS.md, docs/fern/README.md	Updates stable-tag triggers, checks out full history, gates materialization and publishing, ignores generated outputs, and documents release versioning.

Sequence Diagram(s)

sequenceDiagram
  participant Workflow as publish-fern-docs.yaml
  participant Script as materialize-release-versions.mjs
  participant Git as Git tags
  participant Fern as Fern docs configuration
  Workflow->>Script: Run materialize:versions
  Script->>Git: Discover eligible tags
  Git-->>Script: Return tagged docs
  Script->>Script: Generate snapshots and rewrite navigation
  Script->>Fern: Update docs.yml
  Fern-->>Workflow: Provide generated publishing inputs

Loading

Possibly related PRs

• NVIDIA-NeMo/nemo-platform#787: Updates docs/fern/versions/latest.yml, which is used as the eligibility and navigation source by the new release materialization flow.

Suggested labels: docs

Suggested reviewers: mquong-ca

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: generating Fern release versions so the version selector is populated.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fern-version-fix/mck

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 5

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/workflows/publish-fern-docs.yaml:
- Around line 49-56: Add an npm ci step in the publish workflow after the Setup
Node.js step and before the “Materialize release versions” step, using docs/fern
as its working directory so npm run materialize:versions has its yaml dependency
installed.

In `@docs/fern/README.md`:
- Around line 93-107: Separate release versioning guidance by Diataxis type: in
docs/fern/README.md lines 93-107, retain only a concise reference overview and
cross-link a dedicated HOW-TO; move local materialization and preview
instructions there. In docs/AGENTS.md lines 20-27, retain the publication rule
and link to the same HOW-TO without duplicating operational steps. Ensure the
HOW-TO lists prerequisites first and ends with a Next Steps section.

In `@docs/fern/scripts/materialize-release-versions.mjs`:
- Around line 191-195: Update the version navigation generation around
versionYmlPath and writeFileSync to detect an existing file before writing; if
it lacks generatedFileHeader, fail instead of overwriting it. Preserve existing
generated files, and ensure updateDocsYml does not replace entries backed by
hand-authored version nav files.
- Around line 100-107: Update the version metadata construction around
displayName, slug, and dirName so prerelease tags retain their full normalized
version in the generated path instead of collapsing to the final release path.
Ensure generated paths are validated for uniqueness and reject duplicate paths
before materialization, while preserving existing final-release naming behavior.
- Around line 95-97: Classify prereleases using the parsed SemVer prerelease
component rather than checking for any hyphen: update isPrerelease in
materialize-release-versions.mjs while preserving stable build-metadata tags.
Also update .github/workflows/publish-fern-docs.yaml lines 26-27 to use the same
eligibility logic instead of hyphen-based exclusion.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 658e0f95-6cfd-4bca-a5ac-0305948056b8

📥 Commits

Reviewing files that changed from the base of the PR and between dae9035 and 63fa380.

⛔ Files ignored due to path filters (1)

• docs/fern/package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (6)

• .github/workflows/publish-fern-docs.yaml
• .gitignore
• docs/AGENTS.md
• docs/fern/README.md
• docs/fern/package.json
• docs/fern/scripts/materialize-release-versions.mjs

[github-actions]

Suite	Lines Covered	Line Rate	Branch Rate
Unit Tests	27237/34958	77.9%	62.2%
Integration Tests	16000/33670	47.5%	19.9%

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/fern/scripts/materialize-release-versions.mjs`:
- Around line 28-32: Update the publish-fern-docs workflow to install
dependencies in docs/fern before invoking materialize:versions, ensuring the
yaml import in materialize-release-versions.mjs resolves on a clean runner.
After materialization, run make docs-check as part of the workflow.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: bcadbd06-a26c-408a-b0f5-002524a80d70

📥 Commits

Reviewing files that changed from the base of the PR and between 63fa380 and b1a216a.

📒 Files selected for processing (2)

• docs/fern/scripts/materialize-release-versions.mjs
• docs/fern/scripts/sync-helm-docs.mjs

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/workflows/publish-fern-docs.yaml:
- Around line 69-71: Add a separate broken-link validation step before the
Publish Docs step in the workflow, alongside the existing Check Fern docs step,
running make docs-broken-links under the same release eligibility condition.
Preserve the existing make docs-check step and ensure both documentation checks
complete before publishing.
- Around line 57-62: Update the --check-tag handling in
materialize-release-versions.mjs to reuse the tagged-navigation eligibility
check used by discoverReleaseTags(), including requiring the corresponding
docs/fern/versions/latest.yml file. Ensure the release-tag workflow step
consumes this aligned result so tags without the latest.yml snapshot are not
treated as eligible.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: ef0bdff1-0def-4142-a714-137c02379bec

📥 Commits

Reviewing files that changed from the base of the PR and between b1a216a and 751db07.

📒 Files selected for processing (2)

• .github/workflows/publish-fern-docs.yaml
• docs/fern/scripts/materialize-release-versions.mjs

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/fern/scripts/materialize-release-versions.mjs