Skip to content

Commit b679a79

Browse files
authored
docs: turn a couple mentions of flags into cross references (#2146)
I found turning these into clickable links made browsing the docs to understand behavior easier. * Also adds `{flag}` as a valid reference role.
1 parent 5eff339 commit b679a79

File tree

4 files changed

+7
-5
lines changed

4 files changed

+7
-5
lines changed

python/private/common/attributes.bzl

+3-3
Original file line numberDiff line numberDiff line change
@@ -280,11 +280,11 @@ attribute.
280280
doc = """
281281
Whether py source files should be precompiled.
282282
283-
See also: `--precompile` flag, which can override this attribute in some cases.
283+
See also: {flag}`--precompile` flag, which can override this attribute in some cases.
284284
285285
Values:
286286
287-
* `inherit`: Determine the value from the --precompile flag.
287+
* `inherit`: Determine the value from the {flag}`--precompile` flag.
288288
* `enabled`: Compile Python source files at build time. Note that
289289
--precompile_add_to_runfiles affects how the compiled files are included into
290290
a downstream binary.
@@ -333,7 +333,7 @@ runtime when the code actually runs.
333333
Determines, when a source file is compiled, if the source file is kept
334334
in the resulting output or not. Valid values are:
335335
336-
* `inherit`: Inherit the value from the `--precompile_source_retention` flag.
336+
* `inherit`: Inherit the value from the {flag}`--precompile_source_retention` flag.
337337
* `keep_source`: Include the original Python source.
338338
* `omit_source`: Don't include the original py source.
339339
* `omit_if_generated_source`: Keep the original source if it's a regular source

python/private/common/py_executable.bzl

+2-2
Original file line numberDiff line numberDiff line change
@@ -96,14 +96,14 @@ filename in `srcs`, `main` must be specified.
9696
doc = """
9797
Determines whether pyc files from dependencies should be manually included.
9898
99-
NOTE: This setting is only useful with `--precompile_add_to_runfiles=decided_elsewhere`.
99+
NOTE: This setting is only useful with {flag}`--precompile_add_to_runfiles=decided_elsewhere`.
100100
101101
Valid values are:
102102
* `include_pyc`: Add pyc files from dependencies in the binary (from
103103
`PyInfo.transitive_pyc_files`.
104104
* `disabled`: Don't explicitly add pyc files from dependencies. Note that
105105
pyc files may still come from dependencies if a target includes them as
106-
part of their runfiles (such as when `--precompile_add_to_runfiles=always`
106+
part of their runfiles (such as when {obj}`--precompile_add_to_runfiles=always`
107107
is used).
108108
""",
109109
),

sphinxdocs/docs/sphinx-bzl.md

+1
Original file line numberDiff line numberDiff line change
@@ -106,6 +106,7 @@ searched and matched. Supported cross reference roles are:
106106

107107
* `{bzl:arg}`: Refer to a function argument.
108108
* `{bzl:attr}`: Refer to a rule attribute.
109+
* `{bzl:flag}`: Refer to a flag.
109110
* `{bzl:obj}`: Refer to any type of Bazel object
110111
* `{bzl:rule}`: Refer to a rule.
111112
* `{bzl:target}`: Refer to a target.

sphinxdocs/src/sphinx_bzl/bzl.py

+1
Original file line numberDiff line numberDiff line change
@@ -1410,6 +1410,7 @@ class _BzlDomain(domains.Domain):
14101410
"arg": roles.XRefRole(),
14111411
"attr": roles.XRefRole(),
14121412
"default-value": _DefaultValueRole(),
1413+
"flag": roles.XRefRole(),
14131414
"obj": roles.XRefRole(),
14141415
"required-providers": _RequiredProvidersRole(),
14151416
"return-type": _ReturnTypeRole(),

0 commit comments

Comments
 (0)