diff --git a/python/private/common/attributes.bzl b/python/private/common/attributes.bzl
index 503578b78..1878284f3 100644
--- a/python/private/common/attributes.bzl
+++ b/python/private/common/attributes.bzl
@@ -280,11 +280,11 @@ attribute.
             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 @@ runtime when the code actually runs.
 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 2b4a9397c..d1cbea978 100644
--- a/python/private/common/py_executable.bzl
+++ b/python/private/common/py_executable.bzl
@@ -96,14 +96,14 @@ filename in `srcs`, `main` must be specified.
             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 c6dc430dd..331e04acd 100644
--- a/sphinxdocs/docs/sphinx-bzl.md
+++ b/sphinxdocs/docs/sphinx-bzl.md
@@ -106,6 +106,7 @@ searched and matched. Supported cross reference roles are:
 
 * `{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 d09914b31..ad2fd289d 100644
--- a/sphinxdocs/src/sphinx_bzl/bzl.py
+++ b/sphinxdocs/src/sphinx_bzl/bzl.py
@@ -1410,6 +1410,7 @@ class _BzlDomain(domains.Domain):
         "arg": roles.XRefRole(),
         "attr": roles.XRefRole(),
         "default-value": _DefaultValueRole(),
+        "flag": roles.XRefRole(),
         "obj": roles.XRefRole(),
         "required-providers": _RequiredProvidersRole(),
         "return-type": _ReturnTypeRole(),