docs: Fix nearly all xref errors and other doc warnings

CHANGELOG.md

@@ -69,7 +69,7 @@ END_UNRELEASED_TEMPLATE
   `//python/config_setting/...` and the `@platforms` package instead.
 * (binaries/tests) The `PYTHONBREAKPOINT` environment variable is automatically inherited
 * (binaries/tests) The {obj}`stamp` attribute now transitions the Bazel builtin
-  {obj}`--stamp` flag.
+  {flag}`--stamp` flag.
 * (pypi) Now the RECORD file patches will follow the quoted or unquoted filenames convention
   in order to make `pytorch` and friends easier to patch.
 * (wheel) `py_wheel` no longer expands the input depset during analysis,
@@ -99,7 +99,7 @@ END_UNRELEASED_TEMPLATE
   to add to binaries/tests for custom debuggers.
 * (binaries/tests) Build information is now included in binaries and tests.
   Use the `bazel_binary_info` module to access it. The {flag}`--stamp` flag will
-  add {flag}`--workspace_status` information.
+  add {obj}`--workspace_status_command` information.
 * (gazelle) A new directive `python_generate_pyi_deps` has been added. When
   `true`, a `py_*` target's `pyi_srcs` attribute will be set if any `.pyi` files
   that are associated with the target's `srcs` are present.
@@ -176,7 +176,7 @@ END_UNRELEASED_TEMPLATE
   to pass the `TOOL_VERSIONS` that include 3.8 toolchains or use the `bzlmod` APIs to add
   them back. This means any hub `pip.parse` calls that target `3.8` will be ignored from
   now on. ([#2704](https://github.com/bazel-contrib/rules_python/issues/2704))
-  {object}`python.single_version_override`, like:
+  {bzl:obj}`python.single_version_override`, like:
 
   ```starlark
   python = use_extension("@rules_python//python/extensions:python.bzl", "python")
@@ -291,10 +291,10 @@ END_UNRELEASED_TEMPLATE
   [#2949](https://github.com/bazel-contrib/rules_python/issues/2949) if you run into any
   problems.
   With this release we are deprecating {obj}`pip.parse.experimental_target_platforms` and
-  {obj}`pip_repository.experimental_target_platforms`. For users using `WORKSPACE` and
+  `pip_repository.experimental_target_platforms`. For users using `WORKSPACE` and
   vendoring the `requirements.bzl` file, please re-vendor so that downstream is unaffected
   when the APIs get removed. If you need to customize the way the dependencies get
-  evaluated, see [our docs](/pypi/download.html#customizing-requires-dist-resolution) on customizing `Requires-Dist` resolution.
+  evaluated, see [our docs](https://rules-python.readthedocs.io/en/latest/pypi/download.html#customizing-requires-dist-resolution) on customizing `Requires-Dist` resolution.
 * (toolchains) Added Python versions 3.15.0a1, 3.14.0, 3.13.9, 3.12.12, 3.11.14, 3.10.19, and 3.9.24
   from the [20251014] release.
 * (deps) (bzlmod) Upgraded to `bazel-skylib` version
@@ -374,7 +374,7 @@ END_UNRELEASED_TEMPLATE
   the right wheel when there are multiple wheels for the target platform
   (e.g. `musllinux_1_1_x86_64` and `musllinux_1_2_x86_64`). If the user
   wants to set the minimum version for the selection algorithm, use the
-  {attr}`pip.defaults.whl_platform_tags` attribute to configure that. If
+  {obj}`pip.default.whl_platform_tags` attribute to configure that. If
   `musllinux_*_x86_64` is specified, we will choose the lowest available
   wheel version. Fixes [#3250](https://github.com/bazel-contrib/rules_python/issues/3250).
 

docs/BUILD.bazel

@@ -89,6 +89,7 @@ sphinx_stardocs(
         "//python:features_bzl",
         "//python:packaging_bzl",
         "//python:pip_bzl",
+        "//python:proto_bzl",
         "//python:py_binary_bzl",
         "//python:py_cc_link_params_info_bzl",
         "//python:py_exec_tools_info_bzl",
@@ -111,6 +112,7 @@ sphinx_stardocs(
         "//python/extensions:python_bzl",
         "//python/local_toolchains:repos_bzl",
         "//python/private:attr_builders_bzl",
+        "//python/private:builders_bzl",
         "//python/private:builders_util_bzl",
         "//python/private:py_binary_rule_bzl",
         "//python/private:py_cc_toolchain_rule_bzl",

docs/_includes/py_console_script_binary.md

@@ -12,7 +12,8 @@ py_console_script_binary(
 )
 ```
 
-#### Specifying extra dependencies
+:::{rubric} Specifying extra dependencies
+:::
 You can also specify extra dependencies and the
 exact script name you want to call. This is useful for tools like `flake8`,
 `pylint`, and `pytest`, which have plugin discovery methods and discover
@@ -36,7 +37,8 @@ py_console_script_binary(
 )
 ```
 
-#### Using a specific Python version
+:::{rubric} Using a specific Python version
+:::
 
 A specific Python version can be forced by passing the desired Python version, e.g. to force Python 3.9:
 ```starlark
@@ -49,7 +51,8 @@ py_console_script_binary(
 )
 ```
 
-#### Adding a Shebang Line
+:::{rubric} Adding a Shebang Line
+:::
 
 You can specify a shebang line for the generated binary. This is useful for Unix-like
 systems where the shebang line determines which interpreter is used to execute
@@ -69,7 +72,8 @@ Note that to execute via the shebang line, you need to ensure the specified
 Python interpreter is available in the environment.
 
 
-#### Using a specific Python Version directly from a Toolchain
+:::{rubric} Using a specific Python Version directly from a Toolchain
+:::
 :::{deprecated} 1.1.0
 The toolchain-specific `py_binary` and `py_test` symbols are aliases to the regular rules.
 For example, `load("@python_versions//3.11:defs.bzl", "py_binary")` and `load("@python_versions//3.11:defs.bzl", "py_test")` are deprecated.

docs/api/rules_python/python/config_settings/index.md

@@ -169,7 +169,7 @@ If you need to match a version that isn't present, then you have two options:
    )
    ```
 
-2. Use {obj}`python.single_override` to re-introduce the desired version so
+2. Use {obj}`python.single_version_override` to re-introduce the desired version so
    that the corresponding `//python/config_setting:is_python_XXX` target is
    generated.
 :::

docs/conf.py

@@ -107,15 +107,33 @@
 primary_domain = None  # The default is 'py', which we don't make much use of
 nitpicky = True
 
+# Ignore nitpicks for missing cross-references to external objects.
+# These are typically objects that aren't documented or aren't easily linked
+# via intersphinx mapping, so we suppress warnings for them to keep the build clean.
 nitpick_ignore_regex = [
-    # External xrefs aren't setup: ignore missing xref warnings
-    # External xrefs to sphinx isn't setup: ignore missing xref warnings
-    ("py:.*", "(sphinx|docutils|ast|enum|collections|typing_extensions).*"),
+    ("py:class", r"docutils\..*"),
+    ("py:obj", r"sphinx\.util\.docutils\..*"),
+    ("py:obj", r"sphinx\.util\.docfields\..*"),
+    ("py:class", r"sphinx\.util\.typing\..*"),
+    ("py:class", r"sphinx_bzl\.bzl\..*"),
+    ("py:class", r"typing_extensions\.TypeAlias"),
+    ("bzl:obj", r":current_py_cc_headers_abi3"),
+    ("bzl:obj", r":python"),
+    ("bzl:type", r"T"),
+    ("bzl:type", r"input_value"),
+    ("bzl:type", r"DepsetBuilder"),
+    ("bzl:type", r"RunfilesBuilder"),
+    ("bzl:type", r"BuiltinPyInfo"),
+    ("bzl:type", r".*SentinelInfo"),
+    ("bzl:type", r".*SphinxDocsLibraryInfo"),
+    ("bzl:type", r".*_SphinxRunInfo"),
 ]
 
 # --- Intersphinx configuration
 
 intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "sphinx": ("https://www.sphinx-doc.org/en/master", None),
     "bazel": ("https://bazel.build/", "bazel_inventory.inv"),
 }
 

docs/devguide.md

@@ -117,6 +117,7 @@ to have everything self-documented, we have a special target,
 of the requirement-updating scripts in sequence in one go. This can be done once per release as
 we prepare for releases.
 
+(creating-backport-prs)=
 ## Creating Backport PRs
 
 The steps to create a backport PR are:

docs/environment-variables.md

@@ -29,7 +29,7 @@ The guide on {any}`How to integrate a debugger`
 :::{versionadded} 1.3.0
 :::
 :::{versionchanged} 1.7.0
-Support added for {obj}`--bootstrap_impl=system_python`.
+Support added for {bzl:flag}`--bootstrap_impl=system_python`.
 :::
 
 ::::

docs/howto/multi-platform-pypi-deps.md

@@ -48,15 +48,15 @@ Additional dimensions should be appended and separated with an underscore (e.g.
 `linux_x86_64_musl_cuda12.9_numpy2`).
 
 The platform name should not include the Python version. That is handled by
-`pip.parse.python_version` separately.
+{attr}`pip.parse.python_version` separately.
 
 :::{note}
 The term _platform_ here has nothing to do with Bazel's `platform()` rule.
 :::
 
 #### Defining custom settings
 
-Because {obj}`pip.parse.config_settings` is a list of arbitrary `config_setting`
+Because {attr}`pip.default.config_settings` is a list of arbitrary `config_setting`
 targets, you can define your own flags or implement custom config matching
 logic. This allows you to model settings that aren't inherently part of
 rules_python.
@@ -85,7 +85,7 @@ contains commonly used settings for OS and CPU:
 * `@platforms//cpu:aarch64`
 
 Note that these are the raw flag names. In order to use them with `pip.default`,
-you must use {obj}`config_setting()` to match a particular value for them.
+you must use {obj}`config_setting` to match a particular value for them.
 
 ### Associating Requirements to Platforms
 

docs/pypi/download-workspace.md

@@ -41,7 +41,6 @@ re-executed to pick up a non-hermetic change to your environment (e.g., updating
 your system `python` interpreter), you can force it to re-execute by running
 `bazel sync --only [pip_parse name]`.
 
-(per-os-arch-requirements)=
 ## Requirements for a specific OS/Architecture
 
 In some cases, you may need to use different requirements files for different OS and architecture combinations.

docs/pypi/index.md

@@ -1,6 +1,7 @@
 :::{default-domain} bzl
 :::
 
+(pypi-dependencies)=
 # Using PyPI
 
 Using PyPI packages (aka "pip install") involves the following main steps:

docs/support.md

@@ -25,10 +25,9 @@ patch 1.4, version 1.5 must be patched first.
 
 Backports can be requested by [creating an issue with the patch release
 template][patch-release-issue] or by sending a pull request performing the backport.
-See the dev guide for [how to create a backport PR][backport-pr].
+See the dev guide for [how to create a backport PR](creating-backport-prs).
 
 [patch-release-issue]: https://github.com/bazelbuild/rules_python/issues/new?template=patch_release_request.md
-[backport-pr]: devguide.html#creating-backport-prs
 
 ## Supported Bazel Versions
 

docs/toolchains.md

@@ -852,8 +852,7 @@ environment variable automatically. The `//python/bin:python` target will not.
 The following targets expose the headers and libraries from the
 currently selected Python C toolchain:
 
-- {obj}`@rules_python//python/cc:`
-`current_py_cc_headers`
+- {obj}`@rules_python//python/cc:current_py_cc_headers`
 - {obj}`@rules_python//python/cc:current_py_cc_headers_abi3`
 - {obj}`@rules_python//python/cc:current_py_cc_libs`
 
@@ -872,5 +871,5 @@ compatibility across different toolchain configurations.
 
 :::{seealso}
 The _How to get Python headres for C extensions_ how-to guide, and the
-{obj}`@rules_python//python/cc` package API documentation.
+{obj}`//python/cc:BUILD.bazel` package API documentation.
 :::

gazelle/docs/annotations.md

@@ -22,27 +22,28 @@ def bar():  # gazelle:annotation_name value
 The annotations are:
 
 {.glossary}
-[`# gazelle:ignore imports`](#ignore)
+[`# gazelle:ignore imports`](#annotation-ignore)
 : Tells Gazelle to ignore import statements. `imports` is a comma-separated
   list of imports to ignore.
   * Default: n/a
   * Allowed Values: A comma-separated string of python package names
 
-[`# gazelle:include_dep targets`](#include-dep)
+[`# gazelle:include_dep targets`](#annotation-include-dep)
 : Tells Gazelle to include a set of dependencies, even if they are not imported
   in a Python module. `targets` is a comma-separated list of target names
   to include as dependencies.
   * Default: n/a
   * Allowed Values: A comma-separated string of targets
 
-[`# gazelle:include_pytest_conftest bool`](#include-pytest-conftest)
+[`# gazelle:include_pytest_conftest bool`](#annotation-include-pytest-conftest)
 : Whether or not to include a sibling `:conftest` target in the `deps`
   of a {bzl:obj}`py_test` target. The default behaviour is to include `:conftest`
   (i.e.: `# gazelle:include_pytest_conftest true`).
   * Default: n/a
   * Allowed Values: `true`, `false`
 
 
+(annotation-ignore)=
 ## `ignore`
 
 This annotation accepts a comma-separated string of values. Values are names of
@@ -75,6 +76,7 @@ deps = ["@pypi//numpy"],
 ```
 
 
+(annotation-include-dep)=
 ## `include_dep`
 
 This annotation accepts a comma-separated string of values. Values _must_