docs: generate docs for py_common, PyInfoBuilder APIs (bazel-contrib#2920)

I wrote up the docs awhile, but didn't fully wire them through to the doc gen. Fixes some various issues with the generated docs along the way.

Author: rickeylev

docs/BUILD.bazel

@@ -113,6 +113,7 @@ sphinx_stardocs(
  "//python/private:builders_util_bzl",
  "//python/private:py_binary_rule_bzl",
  "//python/private:py_cc_toolchain_rule_bzl",
+ "//python/private:py_info_bzl",
  "//python/private:py_library_rule_bzl",
  "//python/private:py_runtime_rule_bzl",
  "//python/private:py_test_rule_bzl",

python/api/api.bzl

@@ -1,4 +1,23 @@
-"""Public, analysis phase APIs for Python rules."""
+"""Public, analysis phase APIs for Python rules.
+
+To use the analyis-time API, add the attributes to your rule, then
+use `py_common.get()` to get the api object:
+
+```
+load("@rules_python//python/api:api.bzl", "py_common")
+
+def _impl(ctx):
+ py_api = py_common.get(ctx)
+
+myrule = rule(
+ implementation = _impl,
+ attrs = {...} | py_common.API_ATTRS
+)
+```
+
+:::{versionadded} 0.37.0
+:::
+"""
 
 load("//python/private/api:api.bzl", _py_common = "py_common")
 

python/private/api/api.bzl

@@ -27,6 +27,17 @@ will depend on the target that is providing the API struct.
  },
 )
 
+def _py_common_typedef():
+ """Typedef for py_common.
+
+ :::{field} API_ATTRS
+ :type: dict[str, Attribute]
+
+ The attributes that rules must have for `py_common.get()` to work.
+ :::
+
+ """
+
 def _py_common_get(ctx):
  """Get the py_common API instance.
 
@@ -45,6 +56,7 @@ def _py_common_get(ctx):
  return ctx.attr._py_common_api[ApiImplInfo].impl
 
 py_common = struct(
+ TYPEDEF = _py_common_typedef,
  get = _py_common_get,
  API_ATTRS = {
  "_py_common_api": attr.label(

python/private/api/py_common_api.bzl

@@ -22,17 +22,40 @@ def _py_common_api_impl(ctx):
 
 py_common_api = rule(
  implementation = _py_common_api_impl,
- doc = "Rule implementing py_common API.",
+ doc = "Internal Rule implementing py_common API.",
 )
 
+def _py_common_api_typedef():
+ """The py_common API implementation.
+
+ An instance of this object is obtained using {obj}`py_common.get()`
+ """
+
 def _merge_py_infos(transitive, *, direct = []):
- builder = PyInfoBuilder()
+ """Merge PyInfo objects into a single PyInfo.
+
+ This is a convenience wrapper around {obj}`PyInfoBuilder.merge_all`. For
+ more control over merging PyInfo objects, use {obj}`PyInfoBuilder`.
+
+ Args:
+ transitive: {type}`list[PyInfo]` The PyInfo objects with info
+ considered indirectly provided by something (e.g. via
+ its deps attribute).
+ direct: {type}`list[PyInfo]` The PyInfo objects that are
+ considered directly provided by something (e.g. via
+ the srcs attribute).
+
+ Returns:
+ {type}`PyInfo` A PyInfo containing the merged values.
+ """
+ builder = PyInfoBuilder.new()
  builder.merge_all(transitive, direct = direct)
  return builder.build()
 
 # Exposed for doc generation, not directly used.
 # buildifier: disable=name-conventions
 PyCommonApi = struct(
+ TYPEDEF = _py_common_api_typedef,
  merge_py_infos = _merge_py_infos,
- PyInfoBuilder = PyInfoBuilder,
+ PyInfoBuilder = PyInfoBuilder.new,
 )

python/private/common.bzl

@@ -405,7 +405,7 @@ def create_py_info(
  transitive sources collected from dependencies (the latter is only
  necessary for deprecated extra actions support).
  """
- py_info = PyInfoBuilder()
+ py_info = PyInfoBuilder.new()
  py_info.site_packages_symlinks.add(site_packages_symlinks)
  py_info.direct_original_sources.add(original_sources)
  py_info.direct_pyc_files.add(required_pyc_files)