docs: generate docs for py_common, PyInfoBuilder APIs (#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)