docs: docgen underlying rules for macro-wrapped rules (#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 <240938+aignas@users.noreply.github.com>
diff --git a/docs/sphinx/BUILD.bazel b/docs/sphinx/BUILD.bazel
index f82d43a..fe0da1f 100644
--- a/docs/sphinx/BUILD.bazel
+++ b/docs/sphinx/BUILD.bazel
@@ -86,6 +86,10 @@
"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",
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")
