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.

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

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).
 """,
  ),

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.

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(),