Skip to content

Commit 4e76096

Browse files
authored
feat(sphinxdocs): support documenting flag scope in bzl:flag (#4488)
Bazel Starlark build flags can configure a `scope` (such as `universal` or `project`), which determines how flag values propagate across configurations, but `{bzl:flag}` had no way to record it. Add a `:scope:` option to `{bzl:flag}` that renders a `Scope:` field at the top of the flag description, and document `:scope: universal` on universal flags in `//python/config_settings`.
1 parent db252ef commit 4e76096

5 files changed

Lines changed: 121 additions & 9 deletions

File tree

‎docs/api/rules_python/python/config_settings/index.md‎

Lines changed: 18 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55

66
# //python/config_settings
77

8-
:::{bzl:flag} add_srcs_to_runfiles
8+
::::{bzl:flag} add_srcs_to_runfiles
99
Determines if the `srcs` of targets are added to their runfiles.
1010

1111
More specifically, the sources added to runfiles are the `.py` files in `srcs`.
@@ -17,14 +17,16 @@ Values:
1717
behavior is `disabled`.
1818
* `disabled`: Don't add `srcs` to a target's runfiles.
1919
* `enabled`: Add `srcs` to a target's runfiles.
20-
::::{versionadded} 0.37.0
21-
::::
22-
::::{deprecated} 0.37.0
20+
:::{versionadded} 0.37.0
21+
:::
22+
:::{deprecated} 0.37.0
2323
This is a transition flag and will be removed in a subsequent release.
24-
::::
2524
:::
25+
::::
2626

2727
::::{bzl:flag} build_python_zip
28+
:scope: universal
29+
2830
Controls if a `py_binary/py_test` output is a self-executable zipapp.
2931

3032
When enabled, the output of `py_binary` or `py_test` targets will be a
@@ -67,6 +69,8 @@ Setting this flag adds the debugger dependency, but doesn't automatically set
6769
::::
6870

6971
::::{bzl:flag} experimental_python_import_all_repositories
72+
:scope: universal
73+
7074
Controls whether repository directories are added to the import path.
7175

7276
When enabled, the top-level directories in the runfiles root directory (which
@@ -88,7 +92,10 @@ This flag replaces the Bazel builtin
8892
::::
8993

9094
::::{bzl:flag} python_path
91-
A fallback path to use for Python for particular legacy Windows-specific code paths.
95+
:scope: universal
96+
97+
A fallback path to use for Python for particular legacy Windows-specific code
98+
paths.
9299

93100
Deprecated, do not use. This flag is largely a no-op and was replaced by
94101
toolchains. It only remains for some legacy Windows code-paths that will
@@ -105,6 +112,8 @@ Use toolchains instead.
105112
::::
106113

107114
:::{bzl:flag} python_version
115+
:scope: universal
116+
108117
Determines the default hermetic Python toolchain version. This can be set to
109118
one of the values that `rules_python` maintains.
110119
:::
@@ -114,6 +123,8 @@ Parses the value of the `python_version` and transforms it into a `X.Y` value.
114123
:::
115124

116125
::::{bzl:flag} incompatible_default_to_explicit_init_py
126+
:scope: universal
127+
117128
Controls if missing `__init__.py` files are generated or not.
118129

119130
If false, `py_binary` and `py_test` will, for every `*.py` and `*.so` file,
@@ -442,6 +453,7 @@ Values:
442453
::::
443454

444455
::::{bzl:flag} venvs_use_declare_symlink
456+
:scope: universal
445457

446458
Determines if relative symlinks are created using `declare_symlink()` at build
447459
time.

‎sphinxdocs/docs/sphinx-bzl.md‎

Lines changed: 17 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -257,10 +257,25 @@ My docs
257257

258258
:::::
259259

260-
:::{rst:directive} .. bzl:flag:: target
260+
:::::{rst:directive} .. bzl:flag:: target
261261

262-
Documents a flag. It has the same format as `{bzl:target}`
262+
Documents a flag. It has the same target format as `{bzl:target}`.
263+
264+
Directive options:
265+
* `:scope:` specifies the scope of the flag (e.g., `universal` or `target`)
266+
267+
````
268+
:::{bzl:flag} //foo:my_flag
269+
:scope: universal
270+
271+
My docs
263272
:::
273+
````
274+
275+
:::{versionadded} VERSION_NEXT_FEATURE
276+
The `:scope:` directive option was added.
277+
:::
278+
:::::
264279

265280
::::::{rst:directive} .. bzl:typedef:: typename
266281

‎sphinxdocs/sphinxdocs/src/sphinx_bzl/bzl.py‎

Lines changed: 34 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1316,10 +1316,43 @@ def _get_signature_object_type(self) -> str:
13161316
# TODO: Integrate with the option directive, since flags are options, afterall.
13171317
# https://www.sphinx-doc.org/en/master/usage/domains/standard.html#directive-option
13181318
class _BzlFlag(_BzlTarget):
1319-
"""Documents a flag"""
1319+
"""Documents a flag.
1320+
1321+
Flags can optionally have their scope specified using the `:scope:` option.
1322+
1323+
```
1324+
:::{bzl:flag} foo
1325+
:scope: universal
1326+
:::
1327+
```
1328+
"""
13201329

13211330
_TARGET_TYPE = _TargetType.FLAG
13221331

1332+
option_spec = _BzlTarget.option_spec | {
1333+
# keep-sorted start
1334+
"scope": docutils_directives.unchanged_required,
1335+
# keep-sorted end
1336+
}
1337+
1338+
@override
1339+
def transform_content(self, contentnode: addnodes.desc_content) -> None:
1340+
super().transform_content(contentnode)
1341+
scope = self.options.get("scope")
1342+
if not scope:
1343+
return
1344+
field = docutils_nodes.field(
1345+
"",
1346+
docutils_nodes.field_name("", _("Scope")),
1347+
docutils_nodes.field_body("", docutils_nodes.paragraph("", scope)),
1348+
)
1349+
if len(contentnode) > 0 and isinstance(
1350+
contentnode[0], docutils_nodes.field_list
1351+
):
1352+
contentnode[0].insert(0, field)
1353+
else:
1354+
contentnode.insert(0, docutils_nodes.field_list("", field))
1355+
13231356
@override
13241357
def _get_signature_object_type(self) -> str:
13251358
return "flag"

‎sphinxdocs/tests/sphinx_stardoc/sphinx_output_test.py‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -122,6 +122,42 @@ def _doc_element(self, doc):
122122
def test_xrefs(self, text, href):
123123
self.assert_xref("xrefs", text=text, href=href)
124124

125+
def _find_flag_body(self, flag_id):
126+
doc = self._doc_element("target")
127+
for dl in doc.findall(".//dl[@class='bzl flag']"):
128+
if dl.find(f"dt[@id='{flag_id}']") is not None:
129+
return dl.find("dd")
130+
self.fail(f"No flag found with id={flag_id!r}")
131+
132+
def _assert_flag_fields(self, flag_id, expected_fields, expected_paragraphs):
133+
dd = self._find_flag_body(flag_id)
134+
self.assertEqual(["dl", "p"], [child.tag for child in dd])
135+
field_list = dd.find("dl")
136+
self.assertIsNotNone(field_list)
137+
dts = ["".join(dt.itertext()) for dt in field_list.findall("dt")]
138+
dds = ["".join(d.itertext()).strip() for d in field_list.findall("dd")]
139+
self.assertEqual(expected_fields, list(zip(dts, dds, strict=True)))
140+
paragraphs = ["".join(p.itertext()).strip() for p in dd.findall("p")]
141+
self.assertEqual(expected_paragraphs, paragraphs)
142+
143+
def test_flag_without_scope(self):
144+
dd = self._find_flag_body("myflag")
145+
self.assertIsNone(dd.find("dl"))
146+
147+
def test_flag_with_scope(self):
148+
self._assert_flag_fields(
149+
"scopedflag",
150+
[("Scope:", "universal")],
151+
["Some doc about scopedflag"],
152+
)
153+
154+
def test_flag_with_scope_and_existing_field_list(self):
155+
self._assert_flag_fields(
156+
"scopedflag_with_fields",
157+
[("Scope:", "project"), ("Default:", "True")],
158+
["Some doc about scopedflag_with_fields"],
159+
)
160+
125161

126162
if __name__ == "__main__":
127163
absltest.main()

‎sphinxdocs/tests/sphinx_stardoc/target.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,3 +21,19 @@ Some doc about relativetarget
2121
:::{bzl:flag} myflag
2222

2323
:::
24+
25+
:::{bzl:flag} scopedflag
26+
:scope: universal
27+
28+
Some doc about scopedflag
29+
30+
:::
31+
32+
:::{bzl:flag} scopedflag_with_fields
33+
:scope: project
34+
35+
:default: True
36+
37+
Some doc about scopedflag_with_fields
38+
39+
:::

0 commit comments

Comments
 (0)