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.diff --git a/python/private/common/attributes.bzl b/python/private/common/attributes.bzl
index 503578b..1878284 100644
--- a/python/private/common/attributes.bzl
+++ b/python/private/common/attributes.bzl
@@ -280,11 +280,11 @@
doc = """
Whether py source files should be precompiled.
-See also: `--precompile` flag, which can override this attribute in some cases.
+See also: {flag}`--precompile` flag, which can override this attribute in some cases.
Values:
-* `inherit`: Determine the value from the --precompile flag.
+* `inherit`: Determine the value from the {flag}`--precompile` flag.
* `enabled`: Compile Python source files at build time. Note that
--precompile_add_to_runfiles affects how the compiled files are included into
a downstream binary.
@@ -333,7 +333,7 @@
Determines, when a source file is compiled, if the source file is kept
in the resulting output or not. Valid values are:
-* `inherit`: Inherit the value from the `--precompile_source_retention` flag.
+* `inherit`: Inherit the value from the {flag}`--precompile_source_retention` flag.
* `keep_source`: Include the original Python source.
* `omit_source`: Don't include the original py source.
* `omit_if_generated_source`: Keep the original source if it's a regular source
diff --git a/python/private/common/py_executable.bzl b/python/private/common/py_executable.bzl
index 2b4a939..d1cbea9 100644
--- a/python/private/common/py_executable.bzl
+++ b/python/private/common/py_executable.bzl
@@ -96,14 +96,14 @@
doc = """
Determines whether pyc files from dependencies should be manually included.
-NOTE: This setting is only useful with `--precompile_add_to_runfiles=decided_elsewhere`.
+NOTE: This setting is only useful with {flag}`--precompile_add_to_runfiles=decided_elsewhere`.
Valid values are:
* `include_pyc`: Add pyc files from dependencies in the binary (from
`PyInfo.transitive_pyc_files`.
* `disabled`: Don't explicitly add pyc files from dependencies. Note that
pyc files may still come from dependencies if a target includes them as
- part of their runfiles (such as when `--precompile_add_to_runfiles=always`
+ part of their runfiles (such as when {obj}`--precompile_add_to_runfiles=always`
is used).
""",
),
diff --git a/sphinxdocs/docs/sphinx-bzl.md b/sphinxdocs/docs/sphinx-bzl.md
index c6dc430..331e04a 100644
--- a/sphinxdocs/docs/sphinx-bzl.md
+++ b/sphinxdocs/docs/sphinx-bzl.md
@@ -106,6 +106,7 @@
* `{bzl:arg}`: Refer to a function argument.
* `{bzl:attr}`: Refer to a rule attribute.
+* `{bzl:flag}`: Refer to a flag.
* `{bzl:obj}`: Refer to any type of Bazel object
* `{bzl:rule}`: Refer to a rule.
* `{bzl:target}`: Refer to a target.
diff --git a/sphinxdocs/src/sphinx_bzl/bzl.py b/sphinxdocs/src/sphinx_bzl/bzl.py
index d09914b..ad2fd28 100644
--- a/sphinxdocs/src/sphinx_bzl/bzl.py
+++ b/sphinxdocs/src/sphinx_bzl/bzl.py
@@ -1410,6 +1410,7 @@
"arg": roles.XRefRole(),
"attr": roles.XRefRole(),
"default-value": _DefaultValueRole(),
+ "flag": roles.XRefRole(),
"obj": roles.XRefRole(),
"required-providers": _RequiredProvidersRole(),
"return-type": _ReturnTypeRole(),
