Skip to content

Commit 3b183bf

Browse files
rickeylevaignas
andauthored
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]>
1 parent 79478de commit 3b183bf

File tree

6 files changed

+56
-9
lines changed

6 files changed

+56
-9
lines changed

docs/sphinx/BUILD.bazel

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,10 @@ sphinx_stardocs(
8686
"api/python/entry_points/py_console_script_binary.md": "//python/entry_points:py_console_script_binary_bzl",
8787
"api/python/packaging.md": "//python:packaging_bzl",
8888
"api/python/pip.md": "//python:pip_bzl",
89+
"api/python/private/common/py_binary_rule_bazel.md": "//python/private/common:py_binary_rule_bazel_bzl",
90+
"api/python/private/common/py_library_rule_bazel.md": "//python/private/common:py_library_rule_bazel_bzl",
91+
"api/python/private/common/py_runtime_rule.md": "//python/private/common:py_runtime_rule_bzl",
92+
"api/python/private/common/py_test_rule_bazel.md": "//python/private/common:py_test_rule_bazel_bzl",
8993
"api/python/py_binary.md": "//python:py_binary_bzl",
9094
"api/python/py_cc_link_params_info.md": "//python:py_cc_link_params_info_bzl",
9195
"api/python/py_library.md": "//python:py_library_bzl",

python/private/common/py_runtime_rule.bzl

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -160,7 +160,7 @@ in-build runtime may or may not be hermetic, depending on whether it points to
160160
a checked-in interpreter or a wrapper script that accesses the system
161161
interpreter.
162162
163-
# Example
163+
Example
164164
165165
```
166166
load("@rules_python//python:py_runtime.bzl", "py_runtime")

python/py_binary.bzl

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,10 +23,21 @@ load("//python/private/common:py_binary_macro_bazel.bzl", _starlark_py_binary =
2323
_py_binary_impl = _starlark_py_binary if config.enable_pystar else native.py_binary
2424

2525
def py_binary(**attrs):
26-
"""See the Bazel core [py_binary](https://docs.bazel.build/versions/master/be/python.html#py_binary) documentation.
26+
"""Creates an executable Python program.
27+
28+
This is the public macro wrapping the underlying rule. Args are forwarded
29+
on as-is unless otherwise specified. See
30+
the underlying {bzl:obj}`py_binary rule<//python/private/common:py_binary_rule_bazel.bzl%py_binary>`
31+
for detailed attribute documentation.
32+
33+
This macro affects the following args:
34+
* `python_version`: cannot be `PY2`
35+
* `srcs_version`: cannot be `PY2` or `PY2ONLY`
36+
* `tags`: May have special marker values added, if not already present.
2737
2838
Args:
29-
**attrs: Rule attributes
39+
**attrs: Rule attributes forwarded onto the underlying
40+
{bzl:obj}`py_binary rule<//python/private/common:py_binary_rule_bazel.bzl%py_binary>`
3041
"""
3142
if attrs.get("python_version") == "PY2":
3243
fail("Python 2 is no longer supported: https://github.com/bazelbuild/rules_python/issues/886")

python/py_library.bzl

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,10 +23,20 @@ load("//python/private/common:py_library_macro_bazel.bzl", _starlark_py_library
2323
_py_library_impl = _starlark_py_library if config.enable_pystar else native.py_library
2424

2525
def py_library(**attrs):
26-
"""See the Bazel core [py_library](https://docs.bazel.build/versions/master/be/python.html#py_library) documentation.
26+
"""Creates an executable Python program.
27+
28+
This is the public macro wrapping the underlying rule. Args are forwarded
29+
on as-is unless otherwise specified. See
30+
{bzl:obj}`py_library <//python/private/common:py_library_rule_bazel.bzl%py_library>`
31+
for detailed attribute documentation.
32+
33+
This macro affects the following args:
34+
* `srcs_version`: cannot be `PY2` or `PY2ONLY`
35+
* `tags`: May have special marker values added, if not already present.
2736
2837
Args:
29-
**attrs: Rule attributes
38+
**attrs: Rule attributes forwarded onto
39+
{bzl:obj}`py_library <//python/private/common:py_library_rule_bazel.bzl%py_library>`
3040
"""
3141
if attrs.get("srcs_version") in ("PY2", "PY2ONLY"):
3242
fail("Python 2 is no longer supported: https://github.com/bazelbuild/rules_python/issues/886")

python/py_runtime.bzl

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,10 +21,21 @@ load("//python/private/common:py_runtime_macro.bzl", _starlark_py_runtime = "py_
2121
_py_runtime_impl = _starlark_py_runtime if IS_BAZEL_6_OR_HIGHER else native.py_runtime
2222

2323
def py_runtime(**attrs):
24-
"""See the Bazel core [py_runtime](https://docs.bazel.build/versions/master/be/python.html#py_runtime) documentation.
24+
"""Creates an executable Python program.
25+
26+
This is the public macro wrapping the underlying rule. Args are forwarded
27+
on as-is unless otherwise specified. See
28+
{bzl:obj}`py_runtime <//python/private/common:py_runtime_rule.bzl%py_runtime>`
29+
for detailed attribute documentation.
30+
31+
This macro affects the following args:
32+
* `python_version`: cannot be `PY2`
33+
* `srcs_version`: cannot be `PY2` or `PY2ONLY`
34+
* `tags`: May have special marker values added, if not already present.
2535
2636
Args:
27-
**attrs: Rule attributes
37+
**attrs: Rule attributes forwarded onto
38+
{bzl:obj}`py_runtime <//python/private/common:py_runtime_rule.bzl%py_runtime>`
2839
"""
2940
if attrs.get("python_version") == "PY2":
3041
fail("Python 2 is no longer supported: see https://github.com/bazelbuild/rules_python/issues/886")

python/py_test.bzl

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,10 +23,21 @@ load("//python/private/common:py_test_macro_bazel.bzl", _starlark_py_test = "py_
2323
_py_test_impl = _starlark_py_test if config.enable_pystar else native.py_test
2424

2525
def py_test(**attrs):
26-
"""See the Bazel core [py_test](https://docs.bazel.build/versions/master/be/python.html#py_test) documentation.
26+
"""Creates an executable Python program.
27+
28+
This is the public macro wrapping the underlying rule. Args are forwarded
29+
on as-is unless otherwise specified. See
30+
{bzl:obj}`py_test <//python/private/common:py_test_rule_bazel.bzl%py_test>`
31+
for detailed attribute documentation.
32+
33+
This macro affects the following args:
34+
* `python_version`: cannot be `PY2`
35+
* `srcs_version`: cannot be `PY2` or `PY2ONLY`
36+
* `tags`: May have special marker values added, if not already present.
2737
2838
Args:
29-
**attrs: Rule attributes
39+
**attrs: Rule attributes forwarded onto
40+
{bzl:obj}`py_test <//python/private/common:py_test_rule_bazel.bzl%py_test>`
3041
"""
3142
if attrs.get("python_version") == "PY2":
3243
fail("Python 2 is no longer supported: https://github.com/bazelbuild/rules_python/issues/886")

0 commit comments

Comments
 (0)