From b679a794c01c97a82deb2857c374474e32d4c263 Mon Sep 17 00:00:00 2001 From: Richard Levasseur Date: Thu, 22 Aug 2024 15:05:55 -0700 Subject: [PATCH] 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 | 6 +++--- python/private/common/py_executable.bzl | 4 ++-- sphinxdocs/docs/sphinx-bzl.md | 1 + sphinxdocs/src/sphinx_bzl/bzl.py | 1 + 4 files changed, 7 insertions(+), 5 deletions(-) diff --git a/python/private/common/attributes.bzl b/python/private/common/attributes.bzl index 503578b78c..1878284f3a 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 2b4a9397c8..d1cbea978c 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 c6dc430dd6..331e04acd4 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 d09914b318..ad2fd289db 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(),