[docs] Fix moved intersphinx inventory URLs and document mock/intersphinx build behavior

[dstrodtman]

Summary

Two related bits of intersphinx/mocking maintenance for the docs build, plus documenting the build behavior that code contributors need to know about.

Changes

1. Update moved intersphinx inventory URLs (doc/source/conf.py)

The build log emits intersphinx inventory has moved: A -> B for two projects whose docs genuinely relocated:

• pydantic: docs.pydantic.dev/latest/ → pydantic.dev/docs/validation/latest/
• torchvision: pytorch.org/vision/stable/ → docs.pytorch.org/vision/stable/ (matching the existing torch entry)

Both now point at the redirect target, dropping the extra hop and avoiding a hard 404 if the old URLs ever stop redirecting. pandas and scipy are left untouched — their logged "moved" targets are GitHub's normal signed, expiring release-asset URLs, not real moves.

2. Document non-obvious conf.py settings (doc/source/conf.py, comments only)

Comment blocks for intersphinx_mapping (the (base_url, inventory_url) shape, the mirror-inventory rationale, and how to tell a real move from a signed release-asset redirect), remove_from_toctrees, html_sidebars, and autosummary_filename_map.

3. Document API-ref build behavior for contributors (doc/source/ray-contribute/)

The API reference is auto-generated from source, so two build behaviors affect what contributors write in code but weren't documented anywhere:

• Heavy dependencies are mocked (autodoc_mock_imports), so a module that imports one at import time must keep that import safe or the API-ref build breaks. Prefer lazy imports; add new heavy deps to the mock list.
• External types in public signatures link to their upstream docs via intersphinx_mapping; a new external dependency needs an entry to resolve.

Added as a labeled subsection in the docs-contribution guide, with a pointer from the API policy page where a contributor changing a public API is more likely to land.

No behavior change beyond the two URL updates in (1).

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request updates the documentation configuration and contributor guidelines to clarify how the API reference is built and rendered. Specifically, it adds explanatory comments to conf.py, updates external documentation links for pydantic and torchvision, and introduces a new section in the contributor guidelines explaining dependency mocking and type annotation linking via Intersphinx. The reviewer suggested a valuable improvement to clarify that Sphinx's autodoc sets typing.TYPE_CHECKING to True, meaning imports guarded by if TYPE_CHECKING: will still execute and require mocking.