docs: replace viewcode with GitHub permalinks

[njzjz-bot]

Summary

• Replace sphinx.ext.viewcode with sphinx.ext.linkcode.
• Reuse source paths and line ranges already collected by AutoAPI, including local re-exports.
• Pin every source URL to READTHEDOCS_GIT_COMMIT_HASH so links remain immutable.
• Avoid importing backend modules or generating local _modules source pages.

Performance measurement

This PR intentionally contains only the source-link implementation so its Read the Docs preview isolates the Viewcode cost.

Baseline Read the Docs build 33680413:

• total build: 1889 seconds
• dependency installation: 303 seconds
• Sphinx HTML: 1524 seconds
• Viewcode modules highlighted: 712

Both performance PRs use upstream commit 83e7245646185a2de8f7d6277edc4f64b4f500f0 as their base.

Testing

• ruff check .
• ruff format .
• pytest source/tests/test_doc_linkcode.py -v
• Sphinx 9.0.4 integration smoke test confirming a blob/<commit>/...#L10-L20 URL
• Confirmed that the smoke build does not generate an _modules directory

Coding agent: Codex
Codex version: codex-cli 0.144.6
Model: gpt-5.6-sol
Reasoning effort: xhigh

Summary by CodeRabbit

• Documentation

  • Documentation source links now point to the corresponding GitHub files and commit.
  • Python API references include direct links to relevant source code and line ranges.

• Tests

  • Added coverage for source-link generation, commit-specific URLs, line ranges, and unsupported documentation domains.

[coderabbitai]

📝 Walkthrough

Walkthrough

Sphinx documentation switches from viewcode to linkcode, collects AutoAPI source locations, and generates commit-pinned GitHub URLs for Python symbols, including optional line ranges. Tests cover re-export resolution, ReadTheDocs commit selection, and non-Python domain rejection.

Changes

GitHub linkcode integration

Layer / File(s)	Summary
Source location contracts and commit lookup doc/github_linkcode.py	Defines AutoAPI metadata types, repository constants, and validated commit-hash retrieval.
AutoAPI source collection doc/github_linkcode.py	Follows re-exports, identifies in-tree source files, and caches source paths with optional line ranges.
Sphinx wiring and GitHub URL resolution doc/conf.py, doc/github_linkcode.py, source/tests/test_doc_linkcode.py	Enables Sphinx linkcode, registers AutoAPI collection, constructs Python source URLs, and tests resolution behavior.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Sphinx
  participant AutoAPI
  participant linkcode_resolve
  participant GitHub
  Sphinx->>AutoAPI: collect source metadata at builder-inited
  AutoAPI-->>Sphinx: cache source locations
  Sphinx->>linkcode_resolve: resolve Python symbol
  linkcode_resolve->>GitHub: create commit-pinned source URL
  GitHub-->>Sphinx: return source link

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 55.56% 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
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: replacing Sphinx viewcode with GitHub permalinks.
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 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.}

[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 `@source/tests/test_doc_linkcode.py`:
- Line 25: Resolve the temporary repository root before assigning it to the
mocked REPOSITORY_ROOT in the test setup. Update the repository_root assignment
near the test fixture to use tmp_path.resolve(), keeping the existing mock
behavior and assertions unchanged.

🪄 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: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 4eb8f2a0-6184-4e39-a2b8-454e7a66c211

📥 Commits

Reviewing files that changed from the base of the PR and between 83e7245 and d68d412.

📒 Files selected for processing (3)

• doc/conf.py
• doc/github_linkcode.py
• source/tests/test_doc_linkcode.py

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 78.60%. Comparing base (83e7245) to head (d68d412).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #5887      +/-   ##
==========================================
- Coverage   78.87%   78.60%   -0.27%     
==========================================
  Files        1054     1054              
  Lines      121770   121770              
  Branches     4413     4410       -3     
==========================================
- Hits        96046    95720     -326     
- Misses      24159    24472     +313     
- Partials     1565     1578      +13     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.