Merge branch 'main' into refactor/namespace-pkg-star

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/conf.py

@@ -125,6 +125,12 @@
 primary_domain = None  # The default is 'py', which we don't make much use of
 nitpicky = True
 
+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).*"),
+]
+
 # --- Intersphinx configuration
 
 intersphinx_mapping = {

DEVELOPING.md renamed to docs/devguide.md

@@ -1,4 +1,4 @@
-# For Developers
+# Dev Guide
 
 This document covers tips and guidance for working on the rules_python code
 base. A primary audience for it is first time contributors.
@@ -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:
 

docs/getting-started.md

@@ -7,7 +7,7 @@ and the older way of using `WORKSPACE`.
 It assumes you have a `requirements.txt` file with your PyPI dependencies.
 
 For more details information about configuring `rules_python`, see:
-* [Configuring the runtime](toolchains)
+* [Configuring the runtime](configuring-toolchains)
 * [Configuring third party dependencies (pip/pypi)](pypi-dependencies)
 * [API docs](api/index)
 

docs/index.md

@@ -104,6 +104,7 @@ gazelle
 REPL <repl>
 Extending <extending>
 Contributing <contributing>
+devguide
 support
 Changelog <changelog>
 api/index

docs/toolchains.md

@@ -1,6 +1,7 @@
 :::{default-domain} bzl
 :::
 
+(configuring-toolchains)=
 # Configuring Python toolchains and runtimes
 
 This documents how to configure the Python toolchain and runtimes for different

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/private/proto_to_markdown.py

@@ -216,7 +216,9 @@ def _render_repository_rule(self, repo_rule: stardoc_output_pb2.RepositoryRuleIn
             self._render_attributes(repo_rule.attribute)
         if repo_rule.environ:
             self._write(":envvars: ", ", ".join(sorted(repo_rule.environ)))
-        self._write("\n")
+        self._write("\n\n")
+
+        self._write("::::::\n")
 
     def _render_rule(self, rule: stardoc_output_pb2.RuleInfo):
         rule_name = rule.rule_name

sphinxdocs/src/sphinx_bzl/bzl.py

@@ -390,8 +390,12 @@ def _make_xrefs_for_arg_attr(
                     descr=index_description,
                 ),
             ),
-            # This allows referencing an arg as e.g `funcname.argname`
-            alt_names=[anchor_id],
+            alt_names=[
+                # This allows referencing an arg as e.g `funcname.argname`
+                anchor_id,
+                # This allows referencing an arg as simply `argname`
+                arg_name,
+            ],
         )
 
         # Two changes to how arg xrefs are created:
@@ -498,7 +502,55 @@ def run(self) -> list[docutils_nodes.Node]:
         self.env.ref_context["bzl:file"] = file_label
         self.env.ref_context["bzl:object_id_stack"] = []
         self.env.ref_context["bzl:doc_id_stack"] = []
-        return []
+
+        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(
+            _ObjectEntry(
+                full_id=absolute_label,
+                display_name=absolute_label,
+                object_type="obj",
+                search_priority=1,
+                index_entry=domains.IndexEntry(
+                    name=basename,
+                    subtype=_INDEX_SUBTYPE_NORMAL,
+                    docname=self.env.docname,
+                    anchor="",
+                    extra="",
+                    qualifier="",
+                    descr=index_description,
+                ),
+            ),
+            alt_names=[
+                # Allow xref //foo:bar.bzl
+                file_label,
+                # Allow xref bar.bzl
+                basename,
+            ]
+            + extra_alt_names,
+        )
+        index_node = addnodes.index(
+            entries=[
+                _index_node_tuple("single", f"File; {label}", ""),
+            ]
+        )
+        return [index_node]
 
 
 class _BzlAttrInfo(sphinx_docutils.SphinxDirective):
@@ -1156,10 +1208,10 @@ class _BzlTagClass(_BzlCallable):
 
     doc_field_types = [
         _BzlGroupedField(
-            "arg",
+            "attr",
             label=_("Attributes"),
             names=["attr"],
-            rolename="arg",
+            rolename="attr",
             can_collapse=False,
         ),
     ]
@@ -1463,6 +1515,8 @@ class _BzlDomain(domains.Domain):
     # :obj:.
     # NOTE: We also use these object types for categorizing things in the
     # generated index page.
+    # NOTE: The object type keys control what object types are recognized
+    # in inventory files.
     object_types = {
         "arg": domains.ObjType("arg", "arg", "obj"),  # macro/function arg
         "aspect": domains.ObjType("aspect", "aspect", "obj"),
@@ -1486,6 +1540,8 @@ class _BzlDomain(domains.Domain):
         # types are objects that have a constructor and methods/attrs
         "type": domains.ObjType("type", "type", "obj"),
         "typedef": domains.ObjType("typedef", "typedef", "type", "obj"),
+        # generic objs usually come from inventories
+        "obj": domains.ObjType("object", "obj"),
     }
 
     # This controls:
@@ -1710,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