diff --git a/python/private/common/py_runtime_rule.bzl b/python/private/common/py_runtime_rule.bzl
index a7eeb7e..e0b5fb2 100644
--- a/python/private/common/py_runtime_rule.bzl
+++ b/python/private/common/py_runtime_rule.bzl
@@ -160,7 +160,7 @@
 a checked-in interpreter or a wrapper script that accesses the system
 interpreter.
 
-# Example
+Example
 
 ```
 load("@rules_python//python:py_runtime.bzl", "py_runtime")
diff --git a/python/py_binary.bzl b/python/py_binary.bzl
index ed63ebe..f7f68e6 100644
--- a/python/py_binary.bzl
+++ b/python/py_binary.bzl
@@ -23,10 +23,21 @@
 _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")
diff --git a/python/py_library.bzl b/python/py_library.bzl
index 2aa797a..3b9ddd1 100644
--- a/python/py_library.bzl
+++ b/python/py_library.bzl
@@ -23,10 +23,20 @@
 _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")
diff --git a/python/py_runtime.bzl b/python/py_runtime.bzl
index d4b913d..9c8cd00 100644
--- a/python/py_runtime.bzl
+++ b/python/py_runtime.bzl
@@ -21,10 +21,21 @@
 _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")
diff --git a/python/py_test.bzl b/python/py_test.bzl
index f58f067..8f93b27 100644
--- a/python/py_test.bzl
+++ b/python/py_test.bzl
@@ -23,10 +23,21 @@
 _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")