Merge branch 'main' into docs.ignore.py.external.xrefs

Author: aignas

CHANGELOG.md

@@ -66,8 +66,8 @@ END_UNRELEASED_TEMPLATE
 * (rules) On Windows, {obj}`--bootstrap_impl=system_python` is forced. This
   allows setting `--bootstrap_impl=script` in bazelrc for mixed-platform
   environments.
-* (rules) {obj}`pip_compile` now generates a `.test` target. The `_test` target is deprecated
-  and will be removed in the next major release.
+* (rules) {obj}`compile_pip_requirements` now generates a `.test` target. The
+  `_test` target is deprecated and will be removed in the next major release.
   ([#2794](https://github.com/bazel-contrib/rules_python/issues/2794)
 * (py_wheel) py_wheel always creates zip64-capable wheel zips
 
@@ -190,7 +190,7 @@ END_UNRELEASED_TEMPLATE
   packages through SimpleAPI unless they are pulled through direct URL
   references. Fixes [#2023](https://github.com/bazel-contrib/rules_python/issues/2023).
   In case you see issues with `rules_python` being too eager to fetch the SimpleAPI
-  metadata, you can use the newly added {attr}`pip.parse.experimental_skip_sources`
+  metadata, you can use the newly added {attr}`pip.parse.simpleapi_skip`
   to skip metadata fetching for those packages.
 * (uv) A {obj}`lock` rule that is the replacement for the
   {obj}`compile_pip_requirements`. This may still have rough corners
@@ -251,7 +251,7 @@ END_UNRELEASED_TEMPLATE
 
 {#v1-3-0-added}
 ### Added
-* (python) {attr}`python.defaults` has been added to allow users to
+* (python) {obj}`python.defaults` has been added to allow users to
   set the default python version in the root module by reading the
   default version number from a file or an environment variable.
 * {obj}`//python/bin:python`: convenience target for directly running an
@@ -271,7 +271,7 @@ END_UNRELEASED_TEMPLATE
   and py_library rules
   ([#1647](https://github.com/bazel-contrib/rules_python/issues/1647))
 * (rules) Added env-var to allow additional interpreter args for stage1 bootstrap.
-  See {obj}`RULES_PYTHON_ADDITIONAL_INTERPRETER_ARGS` environment variable.
+  See {any}`RULES_PYTHON_ADDITIONAL_INTERPRETER_ARGS` environment variable.
   Only applicable for {obj}`--bootstrap_impl=script`.
 * (rules) Added {obj}`interpreter_args` attribute to `py_binary` and `py_test`,
   which allows pass arguments to the interpreter before the regular args.
@@ -377,7 +377,7 @@ END_UNRELEASED_TEMPLATE
   values. Fixes [#2466](https://github.com/bazel-contrib/rules_python/issues/2466).
 * (py_proto_library) Fix import paths in Bazel 8.
 * (whl_library) Now the changes to the dependencies are correctly tracked when
-  PyPI packages used in {bzl:obj}`whl_library` during the `repository_rule` phase
+  PyPI packages used in `whl_library` during the repository rule phase
   change. Fixes [#2468](https://github.com/bazel-contrib/rules_python/issues/2468).
 + (gazelle) Gazelle no longer ignores `setup.py` files by default. To restore
   this behavior, apply the `# gazelle:python_ignore_files setup.py` directive.
@@ -396,7 +396,7 @@ END_UNRELEASED_TEMPLATE
 * (pypi) Freethreaded packages are now fully supported in the
   {obj}`experimental_index_url` usage or the regular `pip.parse` usage.
   To select the free-threaded interpreter in the repo phase, please use
-  the documented [env](/environment-variables.html) variables.
+  the documented [env](environment-variables) variables.
   Fixes [#2386](https://github.com/bazel-contrib/rules_python/issues/2386).
 * (toolchains) Use the latest astrahl-sh toolchain release [20241206] for Python versions:
     * 3.9.21
@@ -490,7 +490,7 @@ Other changes:
   for the latest toolchain versions for each minor Python version. You can control
   the toolchain selection by using the
   {bzl:obj}`//python/config_settings:py_linux_libc` build flag.
-* (providers) Added {obj}`py_runtime_info.site_init_template` and
+* (providers) Added {obj}`PyRuntimeInfo.site_init_template` and
   {obj}`PyRuntimeInfo.site_init_template` for specifying the template to use to
   initialize the interpreter via venv startup hooks.
 * (runfiles) (Bazel 7.4+) Added support for spaces and newlines in runfiles paths
@@ -688,8 +688,8 @@ Other changes:
 * (bzlmod) The default value for the {obj}`--python_version` flag will now be
   always set to the default python toolchain version value.
 * (bzlmod) correctly wire the {attr}`pip.parse.extra_pip_args` all the
-  way to {obj}`whl_library`. What is more we will pass the `extra_pip_args` to
-  {obj}`whl_library` for `sdist` distributions when using
+  way to `whl_library`. What is more we will pass the `extra_pip_args` to
+  `whl_library` for `sdist` distributions when using
   {attr}`pip.parse.experimental_index_url`. See
   [#2239](https://github.com/bazel-contrib/rules_python/issues/2239).
 * (whl_filegroup): Provide per default also the `RECORD` file
@@ -737,8 +737,8 @@ Other changes:
 
 {#v0-37-0-removed}
 ### Removed
-* (precompiling) {obj}`--precompile_add_to_runfiles` has been removed.
-* (precompiling) {obj}`--pyc_collection` has been removed. The `pyc_collection`
+* (precompiling) `--precompile_add_to_runfiles` has been removed.
+* (precompiling) `--pyc_collection` has been removed. The `pyc_collection`
   attribute now bases its default on {obj}`--precompile`.
 * (precompiling) The {obj}`precompile=if_generated_source` value has been removed.
 * (precompiling) The {obj}`precompile_source_retention=omit_if_generated_source` value has been removed.
@@ -790,7 +790,7 @@ Other changes:
   in extra_requires in py_wheel rule.
 * (rules) Prevent pytest from trying run the generated stage2
   bootstrap .py file when using {obj}`--bootstrap_impl=script`
-* (toolchain) The {bzl:obj}`gen_python_config_settings` has been fixed to include
+* (toolchain) The `gen_python_config_settings` has been fixed to include
   the flag_values from the platform definitions.
 
 {#v0-36-0-added}
@@ -1205,9 +1205,9 @@ Other changes:
   depend on legacy labels instead of the hub repo aliases and you use the
   `experimental_requirement_cycles`, now is a good time to migrate.
 
-[python_default_visibility]: gazelle/README.md#directive-python_default_visibility
+[python_default_visibility]: https://github.com/bazel-contrib/rules_python/tree/main/gazelle/README.md#directive-python_default_visibility
 [test_file_pattern_issue]: https://github.com/bazel-contrib/rules_python/issues/1816
-[test_file_pattern_docs]: gazelle/README.md#directive-python_test_file_pattern
+[test_file_pattern_docs]: https://github.com/bazel-contrib/rules_python/tree/main/gazelle/README.md#directive-python_test_file_pattern
 [20240224]: https://github.com/indygreg/python-build-standalone/releases/tag/20240224.
 [20240415]: https://github.com/indygreg/python-build-standalone/releases/tag/20240415.
 

docs/devguide.md

@@ -39,7 +39,7 @@ more important for tests to balance understandability and maintainability.
 
 ### sh_py_run_test
 
-The [`sh_py_run_test`](tests/support/sh_py_run_test.bzl) rule is a helper to
+The {gh-path}`sh_py_run_test <tests/support/sh_py_run_test.bzl` rule is a helper to
 make it easy to run a Python program with custom build settings using a shell
 script to perform setup and verification. This is best to use when verifying
 behavior needs certain environment variables or directory structures to
@@ -56,6 +56,8 @@ Python binaries and tests with custom build flags. This is best to use when
 verifying behavior that requires specific flags to be set and when the program
 itself can verify the desired state.
 
+They are located in {gh-path}`tests/support/py_reconfig.bzl`
+
 When adding a test, you may find the flag you need to set isn't supported by
 the rule. To have it support setting a new flag:
 

python/private/rule_builders.bzl

@@ -253,7 +253,7 @@ def _ToolchainType_build(self):
         self: implicitly added
 
     Returns:
-        {type}`config_common.toolchain_type`
+        {type}`toolchain_type`
     """
     kwargs = dict(self.kwargs)
     name = kwargs.pop("name")  # Name must be positional
@@ -673,7 +673,7 @@ def _AttrsDict_build(self):
     """Build an attribute dict for passing to `rule()`.
 
     Returns:
-        {type}`dict[str, attribute]` where the values are `attr.XXX` objects
+        {type}`dict[str, Attribute]` where the values are `attr.XXX` objects
     """
     attrs = {}
     for k, v in self.map.items():

sphinxdocs/inventories/bazel_inventory.txt

@@ -3,8 +3,10 @@
 # Version: 7.3.0
 # The remainder of this file is compressed using zlib
 Action bzl:type 1 rules/lib/Action -
+Attribute bzl:type 1 rules/lib/builtins/Attribute -
 CcInfo bzl:provider 1 rules/lib/providers/CcInfo -
 CcInfo.linking_context bzl:provider-field 1 rules/lib/providers/CcInfo#linking_context -
+DefaultInfo bzl:type 1 rules/lib/providers/DefaultInfo -
 ExecutionInfo bzl:type 1 rules/lib/providers/ExecutionInfo -
 File bzl:type 1 rules/lib/File -
 Label bzl:type 1 rules/lib/Label -
@@ -38,6 +40,7 @@ config.string_list bzl:function 1 rules/lib/toplevel/config#string_list -
 config.target bzl:function 1 rules/lib/toplevel/config#target -
 config_common.FeatureFlagInfo bzl:type 1 rules/lib/toplevel/config_common#FeatureFlagInfo -
 config_common.toolchain_type bzl:function 1 rules/lib/toplevel/config_common#toolchain_type -
+ctx bzl:type 1 rules/lib/builtins/repository_ctx -
 ctx.actions bzl:obj 1 rules/lib/builtins/ctx#actions -
 ctx.aspect_ids bzl:obj 1 rules/lib/builtins/ctx#aspect_ids -
 ctx.attr bzl:obj 1 rules/lib/builtins/ctx#attr -
@@ -96,6 +99,7 @@ module_ctx.report_progress bzl:function 1 rules/lib/builtins/module_ctx#report_p
 module_ctx.root_module_has_non_dev_dependency bzl:function 1 rules/lib/builtins/module_ctx#root_module_has_non_dev_dependency -
 module_ctx.watch bzl:function 1 rules/lib/builtins/module_ctx#watch -
 module_ctx.which bzl:function 1 rules/lib/builtins/module_ctx#which -
+native bzl:obj 1 rules/lib/toplevel/native -
 native.existing_rule bzl:function 1 rules/lib/toplevel/native#existing_rule -
 native.existing_rules bzl:function 1 rules/lib/toplevel/native#existing_rules -
 native.exports_files bzl:function 1 rules/lib/toplevel/native#exports_files -
@@ -140,6 +144,8 @@ repository_os bzl:type 1 rules/lib/builtins/repository_os -
 repository_os.arch bzl:obj 1 rules/lib/builtins/repository_os#arch
 repository_os.environ bzl:obj 1 rules/lib/builtins/repository_os#environ
 repository_os.name bzl:obj 1 rules/lib/builtins/repository_os#name
+rule bzl:type 1 rules/lib/builtins/rule -
+rule bzl:function rules/lib/globals/bzl.html#rule -
 runfiles bzl:type 1 rules/lib/builtins/runfiles -
 runfiles.empty_filenames bzl:type 1 rules/lib/builtins/runfiles#empty_filenames -
 runfiles.files bzl:type 1 rules/lib/builtins/runfiles#files -
@@ -156,6 +162,8 @@ testing.TestEnvironment bzl:function 1 rules/lib/toplevel/testing#TestEnvironmen
 testing.analysis_test bzl:rule 1 rules/lib/toplevel/testing#analysis_test -
 toolchain bzl:rule 1 reference/be/platforms-and-toolchains#toolchain -
 toolchain.exec_compatible_with bzl:rule 1 reference/be/platforms-and-toolchains#toolchain.exec_compatible_with -
-toolchain.target_settings bzl:attr 1 reference/be/platforms-and-toolchains#toolchain.target_settings -
 toolchain.target_compatible_with bzl:attr 1 reference/be/platforms-and-toolchains#toolchain.target_compatible_with -
+toolchain.target_settings bzl:attr 1 reference/be/platforms-and-toolchains#toolchain.target_settings -
 toolchain_type bzl:type 1 rules/lib/builtins/toolchain_type.html -
+transition bzl:type 1 rules/lib/builtins/transition -
+tuple bzl:type 1 rules/lib/core/tuple -

sphinxdocs/src/sphinx_bzl/bzl.py

@@ -394,7 +394,7 @@ def _make_xrefs_for_arg_attr(
                 # This allows referencing an arg as e.g `funcname.argname`
                 anchor_id,
                 # This allows referencing an arg as simply `argname`
-                arg_name
+                arg_name,
             ],
         )
 
@@ -503,7 +503,22 @@ def run(self) -> list[docutils_nodes.Node]:
         self.env.ref_context["bzl:object_id_stack"] = []
         self.env.ref_context["bzl:doc_id_stack"] = []
 
-        _, _, basename = file_label.partition(":")
+        package_label, _, basename = file_label.partition(":")
+
+        # Transform //foo/bar:BUILD.bazel into "bar"
+        # This allows referencing "bar" as itself
+        extra_alt_names = []
+        if basename in ("BUILD.bazel", "BUILD"):
+            # Allow xref //foo
+            extra_alt_names.append(package_label)
+            basename = os.path.basename(package_label)
+            # Handle //:BUILD.bazel
+            if not basename:
+                # There isn't a convention for referring to the root package
+                # besides `//:`, which is already the file_label. So just
+                # use some obvious value
+                basename = "__ROOT_BAZEL_PACKAGE__"
+
         index_description = f"File {label}"
         absolute_label = repo + label
         self.env.get_domain("bzl").add_object(
@@ -527,7 +542,8 @@ def run(self) -> list[docutils_nodes.Node]:
                 file_label,
                 # Allow xref bar.bzl
                 basename,
-            ],
+            ]
+            + extra_alt_names,
         )
         index_node = addnodes.index(
             entries=[
@@ -1750,6 +1766,11 @@ def _on_missing_reference(app, env: environment.BuildEnvironment, node, contnode
     # There's no Bazel docs for None, so prevent missing xrefs warning
     if node["reftarget"] == "None":
         return contnode
+
+    # Any and object are just conventions from Python, but useful for
+    # indicating what something is in Starlark, so treat them specially.
+    if node["reftarget"] in ("Any", "object"):
+        return contnode
     return None
 
 

sphinxdocs/tests/sphinx_stardoc/sphinx_output_test.py

@@ -67,6 +67,8 @@ def _doc_element(self, doc):
         ("tag_class_attr_using_attr_role_just_attr_name", "ta1", "module_extension.html#myext.mytag.ta1"),
         ("file_without_repo", "//lang:rule.bzl", "rule.html"),
         ("file_with_repo", "@testrepo//lang:rule.bzl", "rule.html"),
+        ("package_absolute", "//lang", "target.html"),
+        ("package_basename", "lang", "target.html"),
         # fmt: on
     )
     def test_xrefs(self, text, href):

sphinxdocs/tests/sphinx_stardoc/xrefs.md

@@ -51,3 +51,8 @@ Various tests of cross referencing support
 
 * without repo {obj}`//lang:rule.bzl`
 * with repo {obj}`@testrepo//lang:rule.bzl`
+
+## Package refs
+
+* absolute label {obj}`//lang`
+* package basename {obj}`lang`

tests/bootstrap_impls/BUILD.bazel

@@ -13,7 +13,8 @@ load("@rules_shell//shell:sh_test.bzl", "sh_test")
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-load("//tests/support:sh_py_run_test.bzl", "py_reconfig_binary", "py_reconfig_test", "sh_py_run_test")
+load("//tests/support:py_reconfig.bzl", "py_reconfig_binary", "py_reconfig_test")
+load("//tests/support:sh_py_run_test.bzl", "sh_py_run_test")
 load("//tests/support:support.bzl", "SUPPORTS_BOOTSTRAP_SCRIPT")
 load(":venv_relative_path_tests.bzl", "relative_path_test_suite")
 

tests/bootstrap_impls/a/b/c/BUILD.bazel

@@ -1,5 +1,5 @@
 load("//python/private:util.bzl", "IS_BAZEL_7_OR_HIGHER")  # buildifier: disable=bzl-visibility
-load("//tests/support:sh_py_run_test.bzl", "py_reconfig_test")
+load("//tests/support:py_reconfig.bzl", "py_reconfig_test")
 
 _SUPPORTS_BOOTSTRAP_SCRIPT = select({
     "@platforms//os:windows": ["@platforms//:incompatible"],

tests/interpreter/interpreter_tests.bzl

@@ -14,7 +14,7 @@
 
 """This file contains helpers for testing the interpreter rule."""
 
-load("//tests/support:sh_py_run_test.bzl", "py_reconfig_test")
+load("//tests/support:py_reconfig.bzl", "py_reconfig_test")
 
 # The versions of Python that we want to run the interpreter tests against.
 PYTHON_VERSIONS_TO_TEST = (