Skip to content

ci: check Fern broken links#157

Merged
willkill07 merged 1 commit into
NVIDIA:mainfrom
willkill07:wkk_fix-more-broken-links
May 27, 2026
Merged

ci: check Fern broken links#157
willkill07 merged 1 commit into
NVIDIA:mainfrom
willkill07:wkk_fix-more-broken-links

Conversation

@willkill07

@willkill07 willkill07 commented May 27, 2026 •
edited by coderabbitai Bot
Loading

Copy link
Copy Markdown
Member

Overview

Fix generated Rust reference URLs that preserved Rust module underscores in links but not in generated Fern page slugs, and add a strict Fern broken-links check to the docs validation recipe.

  • I confirm this contribution is my own work, or I have the right to submit it under this project's license.
  • I searched existing issues and open pull requests, and this does not duplicate existing work.

Details

  • Split Rust reference output paths from public URLs so generated pages emit explicit rustdoc-compatible slugs for underscore-bearing modules.
  • Add npx fern docs broken-links --strict to just docs and just docs-linkcheck.
  • Fix authored docs links that the stricter Fern broken-link check reports.

Validation performed:

  • uv run --no-sync ruff check scripts/docs/generate_rust_library_reference.py
  • uv run --no-sync ruff format --check scripts/docs/generate_rust_library_reference.py
  • just docs-linkcheck
  • CSV route check for /Users/wkillian/Downloads/link-checker-results-2026-05-27 (1).csv: 90 rows, 0 missing generated routes
  • git diff --check

Where should the reviewer start?

Start with scripts/docs/generate_rust_library_reference.py, especially the distinction between generated file paths and public URL slugs. Then review the justfile docs recipes for the new strict Fern broken-link check.

Related Issues: (use one of the action keywords Closes / Fixes / Resolves / Relates to)

  • Relates to: none

Summary by CodeRabbit

  • Documentation
    • Standardized documentation links throughout the platform to use consistent, absolute URL paths instead of relative references, improving cross-reference clarity.
  • Tests
    • Implemented strict broken link detection in the documentation build pipeline to automatically validate all documentation links before publication.

Review Change Stack

@willkill07
fix broken documentation links
186e4c2 
Signed-off-by: Will Killian <wkillian@nvidia.com>
@willkill07 willkill07 requested a review from a team as a code owner May 27, 2026 03:05
@coderabbitai

coderabbitai Bot commented May 27, 2026 •
edited
Loading

Copy link
Copy Markdown

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Enterprise

Run ID: 612aa497-7425-4fac-9223-6fb072f1a85f

📥 Commits

Reviewing files that changed from the base of the PR and between eb4f71b and 186e4c2.

📒 Files selected for processing (5)
  • docs/observability-plugin/about.mdx
  • docs/resources/support-and-faqs.mdx
  • docs/resources/troubleshooting/index.mdx
  • justfile
  • scripts/docs/generate_rust_library_reference.py
📜 Recent review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
  • GitHub Check: Check / Run
  • GitHub Check: Preview docs
🧰 Additional context used
📓 Path-based instructions (16)
{docs/**,README.md,CONTRIBUTING.md}

📄 CodeRabbit inference engine (.agents/skills/validate-change/SKILL.md)

{docs/**,README.md,CONTRIBUTING.md}: For docs-only changes, run targeted checks only if commands, package names, or examples changed. Use just docs for docs-site builds and just docs-linkcheck when links changed
Run docs site build with just docs

Files:

  • docs/resources/troubleshooting/index.mdx
  • docs/observability-plugin/about.mdx
  • docs/resources/support-and-faqs.mdx
{docs/**,README.md,CONTRIBUTING.md,**/*.md}

📄 CodeRabbit inference engine (.agents/skills/validate-change/SKILL.md)

Run docs link validation with just docs-linkcheck when links change

Files:

  • docs/resources/troubleshooting/index.mdx
  • docs/observability-plugin/about.mdx
  • docs/resources/support-and-faqs.mdx
{docs/**,README.md}

📄 CodeRabbit inference engine (.agents/skills/validate-change/SKILL.md)

Verify README and docs entry points still match current package names and paths for large or public-facing changes

Files:

  • docs/resources/troubleshooting/index.mdx
  • docs/observability-plugin/about.mdx
  • docs/resources/support-and-faqs.mdx
{docs/**,examples/**,README.md}

📄 CodeRabbit inference engine (.agents/skills/validate-change/SKILL.md)

Verify examples still run with documented commands for large or public-facing changes

Files:

  • docs/resources/troubleshooting/index.mdx
  • docs/observability-plugin/about.mdx
  • docs/resources/support-and-faqs.mdx
{docs/**,README.md,**/Cargo.toml,**/package.json,**/*.md}

📄 CodeRabbit inference engine (.agents/skills/validate-change/SKILL.md)

Ensure renamed public surfaces are reflected consistently in manifests and docs for large or public-facing changes

Files:

  • docs/resources/troubleshooting/index.mdx
  • docs/observability-plugin/about.mdx
  • docs/resources/support-and-faqs.mdx
**/*.{md,mdx,py,sh,yaml,yml,toml,json}

📄 CodeRabbit inference engine (.agents/skills/contribute-docs/SKILL.md)

Keep package names, repo references, and build commands current

Files:

  • docs/resources/troubleshooting/index.mdx
  • docs/observability-plugin/about.mdx
  • docs/resources/support-and-faqs.mdx
  • scripts/docs/generate_rust_library_reference.py
**/*.mdx

📄 CodeRabbit inference engine (.agents/skills/contribute-docs/SKILL.md)

In MDX files, top-of-file comments must use JSX comment delimiters: {/* to open and */} to close. Do not use HTML comments for MDX SPDX headers.

MDX top-of-file SPDX comments must use {/* ... */} delimiters instead of HTML comment delimiters (Must-Fix)

Files:

  • docs/resources/troubleshooting/index.mdx
  • docs/observability-plugin/about.mdx
  • docs/resources/support-and-faqs.mdx
**/*.{html,md,mdx}

📄 CodeRabbit inference engine (CONTRIBUTING.md)

Include SPDX license header in HTML and Markdown files using HTML comment syntax

Files:

  • docs/resources/troubleshooting/index.mdx
  • docs/observability-plugin/about.mdx
  • docs/resources/support-and-faqs.mdx
docs/**/*.{md,mdx}

📄 CodeRabbit inference engine (CONTRIBUTING.md)

Update embedded documentation snippets, patch docs, and binding-support notes if examples or supported bindings changed

Files:

  • docs/resources/troubleshooting/index.mdx
  • docs/observability-plugin/about.mdx
  • docs/resources/support-and-faqs.mdx
docs/**

📄 CodeRabbit inference engine (CONTRIBUTING.md)

Run just docs or ./scripts/build-docs.sh html to regenerate ignored Fern API reference pages before validation for documentation site changes

Files:

  • docs/resources/troubleshooting/index.mdx
  • docs/observability-plugin/about.mdx
  • docs/resources/support-and-faqs.mdx
{docs/**,README.md,CONTRIBUTING.md,RELEASING.md,SECURITY.md}

⚙️ CodeRabbit configuration file

{docs/**,README.md,CONTRIBUTING.md,RELEASING.md,SECURITY.md}: Review documentation for technical accuracy against the current API, command correctness, and consistency across language bindings.
Flag stale examples, missing SPDX headers where required, and instructions that no longer match CI or pre-commit behavior.

Files:

  • docs/resources/troubleshooting/index.mdx
  • docs/observability-plugin/about.mdx
  • docs/resources/support-and-faqs.mdx
{.github/**,.gitlab-ci.yml,.pre-commit-config.yaml,justfile,scripts/**}

⚙️ CodeRabbit configuration file

{.github/**,.gitlab-ci.yml,.pre-commit-config.yaml,justfile,scripts/**}: Review automation changes for reproducibility, pinned versions where appropriate, secret handling, and consistency with the documented validation matrix.
Pay attention to commands that need generated native artifacts, FFI libraries, or platform-specific environment variables.

Files:

  • justfile
  • scripts/docs/generate_rust_library_reference.py
{pyproject.toml,**/*.py}

📄 CodeRabbit inference engine (.agents/skills/maintain-packaging/SKILL.md)

Maintain consistency between Python package names in pyproject.toml and import paths used throughout the codebase

Files:

  • scripts/docs/generate_rust_library_reference.py
**/*.{py,txt,toml,cfg,yaml,yml}

📄 CodeRabbit inference engine (.agents/skills/rename-surfaces/SKILL.md)

Update Python package names and top-level module imports during coordinated rename operations

Files:

  • scripts/docs/generate_rust_library_reference.py
{scripts/**,third-party/**}

📄 CodeRabbit inference engine (.agents/skills/validate-change/SKILL.md)

{scripts/**,third-party/**}: For third-party integration or patch changes, run patch validation with ./scripts/apply-patches.sh --check and relevant integration tests. Keep root ./scripts/*.sh wrappers for third-party flows
Run third-party patch bootstrap with ./scripts/bootstrap-third-party.sh
Run third-party patch validation with ./scripts/apply-patches.sh --check

Files:

  • scripts/docs/generate_rust_library_reference.py
**/*.py

📄 CodeRabbit inference engine (.agents/skills/validate-change/SKILL.md)

**/*.py: Run Python formatting with uv run ruff format python
Run Python testing with uv run pytest -k "<pattern>"

**/*.py: Keep SPDX headers on Python source files. The project is Apache-2.0.
Use snake_case for Python binding naming conventions.
Run just test-python for Python binding or wrapper changes.

**/*.py: Use Ruff with rule sets E, F, W, I for Python linting
Use Ruff formatter with line length 120 and double quotes for Python code formatting
Run ty for Python type checking
Use Python snake_case naming convention for Python identifiers
Include SPDX license header in all Python source files using hash comment syntax
Validate Python code with uv run pre-commit run --all-files to enforce Ruff linting and formatting, and ty type checking

Files:

  • scripts/docs/generate_rust_library_reference.py
🔇 Additional comments (5)
scripts/docs/generate_rust_library_reference.py (1)

135-138: LGTM!

Also applies to: 178-185, 213-217

docs/observability-plugin/about.mdx (1)

67-67: LGTM!

docs/resources/support-and-faqs.mdx (1)

156-156: LGTM!

docs/resources/troubleshooting/index.mdx (1)

13-13: LGTM!

justfile (1)

696-696: LGTM!

Also applies to: 706-706

Walkthrough

Documentation links are migrated from relative markdown paths to root-relative and absolute routes. A Python script separates URL path generation from output filename generation using new helper functions. Broken-links validation is integrated into documentation build targets to enforce correctness.

Changes

Documentation URL Standardization

Layer / File(s) Summary
Rust library reference URL generation
scripts/docs/generate_rust_library_reference.py		 _rustdoc_path_part() normalizes URL path components while preserving underscores. _url_relative() computes relative paths for URL generation. _discover_pages() decouples Page.url from Page.output_path by computing the former from _page_url(url_rel) instead of _page_url(output_rel).
Documentation link migration and validation
docs/observability-plugin/about.mdx, docs/resources/support-and-faqs.mdx, docs/resources/troubleshooting/index.mdx, justfile		 Three documentation files update internal hyperlinks from relative markdown paths (../../troubleshooting/trace-incident-runbook.md, ../index.md#anchor, trace-incident-runbook.md) to root-relative and absolute routes (/resources/troubleshooting/trace-incident-runbook, /#what-should-i-read-first). docs and docs-linkcheck targets in justfile add npx fern docs broken-links --strict validation.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

  • NVIDIA/NeMo-Relay#156: Modifies the same documentation files and URL generation script to standardize routing and fix link slugging behavior.
🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title 'ci: check Fern broken links' follows Conventional Commits format with lowercase type 'ci' and provides a clear, concise summary of the changes.
Description check ✅ Passed The description covers all required template sections: Overview (with checkboxes), Details (listing changes), Where to start (reviewer guidance), and Related Issues.
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.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.

Comment @coderabbitai help to get the list of available commands and usage tips.

@github-actions github-actions Bot added size:S PR is small Maintenance CI or Build or general repository maintenance lang:python PR changes/introduces Python code labels May 27, 2026
@github-actions

github-actions Bot commented May 27, 2026

Copy link
Copy Markdown

Fern docs preview: https://nvidia-preview-pull-request-157.docs.buildwithfern.com/nemo/relay (​https://nvidia-preview-pull-request-157.docs.buildwithfern.com/nemo/relay​)

@willkill07 willkill07 self-assigned this May 27, 2026
@willkill07 willkill07 added this to the 0.3 milestone May 27, 2026
@willkill07 willkill07 merged commit ea6864b into NVIDIA:main May 27, 2026
64 of 65 checks passed
@willkill07 willkill07 deleted the wkk_fix-more-broken-links branch May 27, 2026 03:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@willkill07 willkill07

Labels

lang:python PR changes/introduces Python code Maintenance CI or Build or general repository maintenance size:S PR is small

Projects

None yet

Milestone

0.3

Development

Successfully merging this pull request may close these issues.

1 participant

@willkill07