fix: use {doc} role for symlinked doc references for Sphinx 8.2

[raballew]

Summary

• Sphinx 8.2 nitpicky mode follows symlinks when resolving markdown [text](file.md) links, discovering package directories outside the source tree and emitting 47 myst.xref_missing warnings (treated as errors by -W)
• Replace markdown links with MyST {doc} roles for all references to symlinked files (driver docs + MCP doc)
• The {doc} role resolves through Sphinx's document name system which stays within the source tree, avoiding the symlink-following behavior
• Symlinks themselves are unchanged -- driver docs still point to package READMEs

Root cause

The driver doc files (e.g. power.md) are symlinks to package README.md files (e.g. packages/jumpstarter-driver-power/README.md). When index.md references [Power](power.md), Sphinx 8.2 resolves the file path, follows the symlink outside the source tree, and warns about an unresolvable README document in the package directory.

Files changed

• python/docs/source/reference/package-apis/drivers/index.md -- 45 driver links
• python/docs/source/reference/package-apis/index.md -- 1 MCP link
• python/docs/source/getting-started/guides/integration-patterns/agentic.md -- 1 MCP link

Test plan

• make -C python clean-docs && make -C python docs -- zero warnings, build succeeds
• Verified rendered HTML output via local sphinx-autobuild server
• CI check-warnings job passes

🤖 Generated with Claude Code

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 5434af34-d5a4-4055-8065-813c78676558

📥 Commits

Reviewing files that changed from the base of the PR and between eec0278 and 00916e4.

📒 Files selected for processing (3)

• python/docs/source/getting-started/guides/integration-patterns/agentic.md
• python/docs/source/reference/package-apis/drivers/index.md
• python/docs/source/reference/package-apis/index.md

---

📝 Walkthrough

Walkthrough

This pull request updates three documentation files to use Sphinx {doc} role cross-references instead of Markdown links. The changes apply consistently across the Package APIs index, drivers reference index with multiple driver categories, and the agentic integration guide.

Changes

Documentation Sphinx link format updates

Layer / File(s)

Summary

Sphinx {doc} role format migration python/docs/source/reference/package-apis/index.md, python/docs/source/reference/package-apis/drivers/index.md, python/docs/source/getting-started/guides/integration-patterns/agentic.md

Markdown internal links converted to Sphinx {doc} cross-references. Package APIs index entry for MCP, drivers reference index entries for all driver categories across eight sections (System Control, Communication, Storage and Data, Media, Automotive Diagnostics, Flashing and Programming, Emulation, Utility), and the MCP package reference in the agentic guide all adopt the Sphinx format while preserving their reference targets.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Suggested reviewers

• bkhizgiy
• mangelajo
• kirkbrauer
• NickCao

Poem

🐰 From markdown links to Sphinx we go,
Cross-references now in formal flow,
Three docs refactored, patterns aligned,
The builder smiles, consistency signed! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: using Sphinx {doc} roles instead of markdown links for symlinked documentation references to fix Sphinx 8.2 compatibility issues.
Description check	✅ Passed	The description is directly related to the changeset, providing clear context about the root cause (Sphinx 8.2 symlink following), the solution (using {doc} roles), affected files, and test verification.
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.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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