docs: docgen underlying rules for macro-wrapped rules (bazel-contrib#2107)

Rules that have a wrapper macro don't currently show all their
attributes because the
macro hides the rule from stardoc. This also generates docs for the
underlying rules and
has the macro reference them so that users can find all the attributes
the rule accepts.

---------

Co-authored-by: Ignas Anikevicius <[email protected]>

Author: rickeylev

docs/sphinx/BUILD.bazel

@@ -86,6 +86,10 @@ sphinx_stardocs(
         "api/python/entry_points/py_console_script_binary.md": "//python/entry_points:py_console_script_binary_bzl",
         "api/python/packaging.md": "//python:packaging_bzl",
         "api/python/pip.md": "//python:pip_bzl",
+        "api/python/private/common/py_binary_rule_bazel.md": "//python/private/common:py_binary_rule_bazel_bzl",
+        "api/python/private/common/py_library_rule_bazel.md": "//python/private/common:py_library_rule_bazel_bzl",
+        "api/python/private/common/py_runtime_rule.md": "//python/private/common:py_runtime_rule_bzl",
+        "api/python/private/common/py_test_rule_bazel.md": "//python/private/common:py_test_rule_bazel_bzl",
         "api/python/py_binary.md": "//python:py_binary_bzl",
         "api/python/py_cc_link_params_info.md": "//python:py_cc_link_params_info_bzl",
         "api/python/py_library.md": "//python:py_library_bzl",

python/private/common/py_runtime_rule.bzl

@@ -160,7 +160,7 @@ in-build runtime may or may not be hermetic, depending on whether it points to
 a checked-in interpreter or a wrapper script that accesses the system
 interpreter.
 
-# Example
+Example
 
 ```
 load("@rules_python//python:py_runtime.bzl", "py_runtime")

python/py_binary.bzl

@@ -23,10 +23,21 @@ load("//python/private/common:py_binary_macro_bazel.bzl", _starlark_py_binary =
 _py_binary_impl = _starlark_py_binary if config.enable_pystar else native.py_binary
 
 def py_binary(**attrs):
-    """See the Bazel core [py_binary](https://docs.bazel.build/versions/master/be/python.html#py_binary) documentation.
+    """Creates an executable Python program.
+
+    This is the public macro wrapping the underlying rule. Args are forwarded
+    on as-is unless otherwise specified. See
+    the underlying {bzl:obj}`py_binary rule<//python/private/common:py_binary_rule_bazel.bzl%py_binary>`
+    for detailed attribute documentation.
+
+    This macro affects the following args:
+    * `python_version`: cannot be `PY2`
+    * `srcs_version`: cannot be `PY2` or `PY2ONLY`
+    * `tags`: May have special marker values added, if not already present.
 
     Args:
-      **attrs: Rule attributes
+      **attrs: Rule attributes forwarded onto the underlying
+          {bzl:obj}`py_binary rule<//python/private/common:py_binary_rule_bazel.bzl%py_binary>`
     """
     if attrs.get("python_version") == "PY2":
         fail("Python 2 is no longer supported: https://github.com/bazelbuild/rules_python/issues/886")

python/py_library.bzl

@@ -23,10 +23,20 @@ load("//python/private/common:py_library_macro_bazel.bzl", _starlark_py_library
 _py_library_impl = _starlark_py_library if config.enable_pystar else native.py_library
 
 def py_library(**attrs):
-    """See the Bazel core [py_library](https://docs.bazel.build/versions/master/be/python.html#py_library) documentation.
+    """Creates an executable Python program.
+
+    This is the public macro wrapping the underlying rule. Args are forwarded
+    on as-is unless otherwise specified. See
+    {bzl:obj}`py_library <//python/private/common:py_library_rule_bazel.bzl%py_library>`
+    for detailed attribute documentation.
+
+    This macro affects the following args:
+    * `srcs_version`: cannot be `PY2` or `PY2ONLY`
+    * `tags`: May have special marker values added, if not already present.
 
     Args:
-      **attrs: Rule attributes
+      **attrs: Rule attributes forwarded onto
+          {bzl:obj}`py_library <//python/private/common:py_library_rule_bazel.bzl%py_library>`
     """
     if attrs.get("srcs_version") in ("PY2", "PY2ONLY"):
         fail("Python 2 is no longer supported: https://github.com/bazelbuild/rules_python/issues/886")

python/py_runtime.bzl

@@ -21,10 +21,21 @@ load("//python/private/common:py_runtime_macro.bzl", _starlark_py_runtime = "py_
 _py_runtime_impl = _starlark_py_runtime if IS_BAZEL_6_OR_HIGHER else native.py_runtime
 
 def py_runtime(**attrs):
-    """See the Bazel core [py_runtime](https://docs.bazel.build/versions/master/be/python.html#py_runtime) documentation.
+    """Creates an executable Python program.
+
+    This is the public macro wrapping the underlying rule. Args are forwarded
+    on as-is unless otherwise specified. See
+    {bzl:obj}`py_runtime <//python/private/common:py_runtime_rule.bzl%py_runtime>`
+    for detailed attribute documentation.
+
+    This macro affects the following args:
+    * `python_version`: cannot be `PY2`
+    * `srcs_version`: cannot be `PY2` or `PY2ONLY`
+    * `tags`: May have special marker values added, if not already present.
 
     Args:
-      **attrs: Rule attributes
+      **attrs: Rule attributes forwarded onto
+          {bzl:obj}`py_runtime <//python/private/common:py_runtime_rule.bzl%py_runtime>`
     """
     if attrs.get("python_version") == "PY2":
         fail("Python 2 is no longer supported: see https://github.com/bazelbuild/rules_python/issues/886")

python/py_test.bzl

@@ -23,10 +23,21 @@ load("//python/private/common:py_test_macro_bazel.bzl", _starlark_py_test = "py_
 _py_test_impl = _starlark_py_test if config.enable_pystar else native.py_test
 
 def py_test(**attrs):
-    """See the Bazel core [py_test](https://docs.bazel.build/versions/master/be/python.html#py_test) documentation.
+    """Creates an executable Python program.
+
+    This is the public macro wrapping the underlying rule. Args are forwarded
+    on as-is unless otherwise specified. See
+    {bzl:obj}`py_test <//python/private/common:py_test_rule_bazel.bzl%py_test>`
+    for detailed attribute documentation.
+
+    This macro affects the following args:
+    * `python_version`: cannot be `PY2`
+    * `srcs_version`: cannot be `PY2` or `PY2ONLY`
+    * `tags`: May have special marker values added, if not already present.
 
     Args:
-      **attrs: Rule attributes
+      **attrs: Rule attributes forwarded onto
+          {bzl:obj}`py_test <//python/private/common:py_test_rule_bazel.bzl%py_test>`
     """
     if attrs.get("python_version") == "PY2":
         fail("Python 2 is no longer supported: https://github.com/bazelbuild/rules_python/issues/886")