Respect --stamp and --nostamp flags for stamping (#234)

Instead of a boolean stamp attribute, introduce a tristate which uses the value of the --[no]stamp flag by default.

Suggested by @alexeagle at eea50da#r141241326

docs/stardoc_rule.md

@@ -39,7 +39,7 @@ Generates documentation for exported starlark rule definitions in a target starl
 | <a id="stardoc-module_extension_template"></a>module_extension_template |  The input file template for generating documentation of module extensions.   |  `Label("@stardoc//stardoc:templates/markdown_tables/module_extension.vm")` |
 | <a id="stardoc-footer_template"></a>footer_template |  The input file template for generating the footer of the output documentation. Optional.   |  `None` |
 | <a id="stardoc-render_main_repo_name"></a>render_main_repo_name |  Render labels in the main repository with a repo component (either the module name or workspace name).   |  `True` |
-| <a id="stardoc-stamp"></a>stamp |  Whether to provide stamping information to templates.   |  `False` |
+| <a id="stardoc-stamp"></a>stamp |  Whether to provide stamping information to templates, where it can be accessed via `$util.formatBuildTimestamp()` and`$stamping`. Example: <pre><code class="language-vm">Built on `$util.formatBuildTimestamp($stamping.volatile.BUILD_TIMESTAMP, "UTC", "yyyy-MM-dd HH:mm")`</code></pre> Possible values: <ul> <li>`stamp = 1`: Always provide stamping information, even in     [--nostamp](https://bazel.build/docs/user-manual#flag--stamp) builds.     This setting should be avoided, since it potentially kills remote caching for the target     and any downstream actions that depend on it.</li> <li>`stamp = 0`: Do not provide stamping information.</li> <li>`stamp = -1`: Provide stamping information only if the      [--stamp](https://bazel.build/docs/user-manual#flag--stamp) flag is set.</li> </ul> Stamped targets are not rebuilt unless their dependencies change.   |  `-1` |
 | <a id="stardoc-kwargs"></a>kwargs |  Further arguments to pass to stardoc.   |  none |
 
 

stardoc/private/BUILD

@@ -1,11 +1,30 @@
 load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
+load("//stardoc/private:stamp_detector.bzl", "stamp_detector")
 
 bzl_library(
     name = "stardoc_lib",
-    srcs = ["stardoc.bzl"],
+    srcs = [
+        "stamp_detector.bzl",
+        "stardoc.bzl",
+    ],
     visibility = ["//stardoc:__pkg__"],
 )
 
+config_setting(
+    name = "stamp_enabled",
+    values = {"stamp": "1"},
+    visibility = ["//visibility:private"],
+)
+
+stamp_detector(
+    name = "stamp_detector",
+    enabled = select({
+        "stamp_enabled": True,
+        "//conditions:default": False,
+    }),
+    visibility = ["//visibility:private"],
+)
+
 # Sources needed for release tarball.
 filegroup(
     name = "distro_srcs",

stardoc/private/stamp_detector.bzl

@@ -0,0 +1,33 @@
+# Copyright 2024 The Bazel Authors. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Detector for the --stamp flag"""
+
+StampDetectorInfo = provider(
+    doc = "Result of detecting the --stamp flag",
+    fields = {
+        "enabled": "True if --stamp is enabled",
+    },
+)
+
+def _stamp_detector_impl(ctx):
+    return [StampDetectorInfo(enabled = ctx.attr.enabled)]
+
+stamp_detector = rule(
+    _stamp_detector_impl,
+    doc = """Detects if the --stamp flag is enabled""",
+    attrs = {
+        "enabled": attr.bool(mandatory = True, doc = "True if --stamp flag is enabled"),
+    },
+)

stardoc/private/stardoc.bzl

@@ -14,8 +14,21 @@
 
 """Starlark rule for stardoc: a documentation generator tool written in Java."""
 
+load("//stardoc/private:stamp_detector.bzl", "StampDetectorInfo")
+
+def _is_stamp_enabled(ctx):
+    if ctx.attr.stamp == 1:
+        return True
+    elif ctx.attr.stamp == 0:
+        return False
+    elif ctx.attr.stamp == -1:
+        return ctx.attr._stamp_detector[StampDetectorInfo].enabled
+    else:
+        fail("`stamp` is expected to be one of [-1, 0, 1]")
+
 def _renderer_action_run(ctx, out_file, proto_file):
     """Helper for declaring the markdown renderer action"""
+    stamp_enabled = _is_stamp_enabled(ctx)
     renderer_args = ctx.actions.args()
     renderer_args.add("--input=" + str(proto_file.path))
     renderer_args.add("--output=" + str(ctx.outputs.out.path))
@@ -30,7 +43,7 @@ def _renderer_action_run(ctx, out_file, proto_file):
     renderer_args.add("--module_extension_template=" + str(ctx.file.module_extension_template.path))
     if ctx.file.footer_template:
         renderer_args.add("--footer_template=" + str(ctx.file.footer_template.path))
-    if ctx.attr.stamp:
+    if stamp_enabled:
         renderer_args.add("--stamping_stable_status_file=" + str(ctx.info_file.path))
         renderer_args.add("--stamping_volatile_status_file=" + str(ctx.version_file.path))
 
@@ -48,7 +61,7 @@ def _renderer_action_run(ctx, out_file, proto_file):
         inputs.append(ctx.file.table_of_contents_template)
     if ctx.file.footer_template:
         inputs.append(ctx.file.footer_template)
-    if ctx.attr.stamp:
+    if stamp_enabled:
         inputs.append(ctx.info_file)
         inputs.append(ctx.version_file)
 
@@ -122,9 +135,30 @@ _common_renderer_attrs = {
         doc = "The input file template for generating the footer of the output documentation. Optional.",
         allow_single_file = [".vm"],
     ),
-    "stamp": attr.bool(
-        doc = "Whether to provide stamping information to templates",
-        default = False,
+    "stamp": attr.int(
+        doc = """
+        Whether to provide stamping information to templates, where it can be accessed via
+        `$util.formatBuildTimestamp()` and`$stamping`. Example:
+        ```vm
+        Built on `$util.formatBuildTimestamp($stamping.volatile.BUILD_TIMESTAMP, "UTC", "yyyy-MM-dd HH:mm")`
+        ```
+
+        Possible values:
+        * `stamp = 1`: Always provide stamping information, even in
+          [--nostamp](https://bazel.build/docs/user-manual#flag--stamp) builds.
+          This setting should be avoided, since it potentially kills remote caching for the target
+          and any downstream actions that depend on it.
+        * `stamp = 0`: Do not provide stamping information.
+        * `stamp = -1`: Provide stamping information only if the
+           [--stamp](https://bazel.build/docs/user-manual#flag--stamp) flag is set.
+
+        Stamped targets are not rebuilt unless their dependencies change.
+        """,
+        default = -1,
+    ),
+    "_stamp_detector": attr.label(
+        default = "//stardoc/private:stamp_detector",
+        providers = [StampDetectorInfo],
     ),
 }
 
@@ -138,16 +172,13 @@ def _stardoc_markdown_renderer_impl(ctx):
     outputs = [out_file]
     return [DefaultInfo(files = depset(outputs), runfiles = ctx.runfiles(files = outputs))]
 
-# TODO(arostovtsev): replace with ... attrs = { ... } | _common_renderer_attrs
-# in rule definition below after we drop support for Bazel 5.
 _stardoc_markdown_renderer_attrs = {
     "src": attr.label(
         doc = "The .binaryproto file from which to generate documentation.",
         allow_single_file = [".binaryproto"],
         mandatory = True,
     ),
-}
-_stardoc_markdown_renderer_attrs.update(_common_renderer_attrs.items())
+} | _common_renderer_attrs
 
 stardoc_markdown_renderer = rule(
     _stardoc_markdown_renderer_impl,

stardoc/stardoc.bzl

@@ -36,7 +36,7 @@ def stardoc(
         module_extension_template = Label("//stardoc:templates/markdown_tables/module_extension.vm"),
         footer_template = None,
         render_main_repo_name = True,
-        stamp = False,
+        stamp = -1,
         **kwargs):
     """Generates documentation for exported starlark rule definitions in a target starlark file.
 
@@ -63,7 +63,22 @@ def stardoc(
       footer_template: The input file template for generating the footer of the output documentation. Optional.
       render_main_repo_name: Render labels in the main repository with a repo component (either
         the module name or workspace name).
-      stamp: Whether to provide stamping information to templates.
+      stamp: Whether to provide stamping information to templates, where it can be accessed via
+        `$util.formatBuildTimestamp()` and`$stamping`. Example:
+        ```vm
+        Built on `$util.formatBuildTimestamp($stamping.volatile.BUILD_TIMESTAMP, "UTC", "yyyy-MM-dd HH:mm")`
+        ```
+        Possible values:
+        <ul>
+        <li>`stamp = 1`: Always provide stamping information, even in
+            [--nostamp](https://bazel.build/docs/user-manual#flag--stamp) builds.
+            This setting should be avoided, since it potentially kills remote caching for the target
+            and any downstream actions that depend on it.</li>
+        <li>`stamp = 0`: Do not provide stamping information.</li>
+        <li>`stamp = -1`: Provide stamping information only if the
+             [--stamp](https://bazel.build/docs/user-manual#flag--stamp) flag is set.</li>
+        </ul>
+        Stamped targets are not rebuilt unless their dependencies change.
       **kwargs: Further arguments to pass to stardoc.
     """
 

test/BUILD

@@ -351,15 +351,15 @@ stardoc_test(
     golden_file = "testdata/stamping_test/golden.md",
     header_template = "testdata/stamping_test/stamping_header.vm",
     input_file = "testdata/stamping_test/input.bzl",
-    stamp = True,
+    stamp = 1,
 )
 
 stardoc_test(
     name = "stamping_with_stamping_off_test",
     golden_file = "testdata/stamping_test/golden_stamping_off.md",
     header_template = "testdata/stamping_test/stamping_header_stamping_off.vm",
     input_file = "testdata/stamping_test/input.bzl",
-    stamp = False,
+    stamp = 0,
 )
 
 sh_test(

test/testdata/stamping_test/golden.md

@@ -1,6 +1,6 @@
 This Stardoc was built in the `AD` era.
 
-Host empty: `false`.
+Host is a non-empty string.
 
 This key does not exist: ``.
 

test/testdata/stamping_test/stamping_header.vm

@@ -3,7 +3,11 @@
 This Stardoc was built in the `$util.formatBuildTimestamp($stamping.volatile.BUILD_TIMESTAMP, "UTC", "G")` era.
 
 ## Should test a stable value, but stable contains quasi sensitive info, so don't print that in the test output
-Host empty: `$stamping.stable.BUILD_HOST.isEmpty()`.
+#if ($stamping.stable.BUILD_HOST)
+Host is a non-empty string.
+#else
+Host is empty or null.
+#end
 
 ## Sometimes Stardoc is built without --workspace_status_command (e.g. in build tests), luckily "$!foo" will tell
 ## Velocity to ignore null values: