Update generated docs

Author: alexeagle

.bazelci/presubmit.yml

@@ -113,7 +113,7 @@ tasks:
       - //container/go/pkg/compat:go_default_test
       - //container/go/pkg/oci:go_default_test
       - //docker/util:config_stripper_test
-      - //docs:copy_image
+      - //docs:all
       - //tests/container:alpine_custom_attr_digest_test
       - //tests/container:alpine_custom_attr_digest_test_impl
       - //tests/container:alpine_linux_armv6_tar_test_image_tar

docs/BUILD

@@ -1,5 +1,5 @@
+load("@bazel_skylib//rules:diff_test.bzl", "diff_test")
 load("@bazel_skylib//rules:write_file.bzl", "write_file")
-load("@build_bazel_rules_nodejs//:index.bzl", "generated_file_test")
 load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
 
 # Workaround https://github.com/bazelbuild/stardoc/issues/25
@@ -17,8 +17,24 @@ stardoc(
     deps = ["//container:image"],
 )
 
-generated_file_test(
-    name = "copy_image",
-    src = "image.md",
-    generated = ":image.md_",
+diff_test(
+    name = "check_image_doc",
+    file1 = ":image_doc",
+    file2 = "image.md",
+)
+
+write_file(
+    name = "gen_update",
+    out = "update.sh",
+    content = [
+        "#!/usr/bin/env bash",
+        "cd $BUILD_WORKSPACE_DIRECTORY",
+        "cp -fv bazel-bin/docs/image.md_ docs/image.md",
+    ],
+)
+
+sh_binary(
+    name = "update",
+    srcs = ["update.sh"],
+    data = [":image_doc"],
 )

docs/image.md

@@ -9,14 +9,14 @@ more specialized build leveraging the same implementation.
 ## container_image_
 
 <pre>
-container_image_(<a href="#container_image_-name">name</a>, <a href="#container_image_-architecture">architecture</a>, <a href="#container_image_-base">base</a>, <a href="#container_image_-build_layer">build_layer</a>, <a href="#container_image_-cmd">cmd</a>, <a href="#container_image_-compression">compression</a>, <a href="#container_image_-compression_options">compression_options</a>,
-                 <a href="#container_image_-create_image_config">create_image_config</a>, <a href="#container_image_-creation_time">creation_time</a>, <a href="#container_image_-data_path">data_path</a>, <a href="#container_image_-debs">debs</a>, <a href="#container_image_-directory">directory</a>, <a href="#container_image_-docker_run_flags">docker_run_flags</a>,
-                 <a href="#container_image_-empty_dirs">empty_dirs</a>, <a href="#container_image_-empty_files">empty_files</a>, <a href="#container_image_-enable_mtime_preservation">enable_mtime_preservation</a>, <a href="#container_image_-entrypoint">entrypoint</a>, <a href="#container_image_-env">env</a>,
-                 <a href="#container_image_-experimental_tarball_format">experimental_tarball_format</a>, <a href="#container_image_-extract_config">extract_config</a>, <a href="#container_image_-files">files</a>, <a href="#container_image_-incremental_load_template">incremental_load_template</a>,
+container_image_(<a href="#container_image_-name">name</a>, <a href="#container_image_-architecture">architecture</a>, <a href="#container_image_-base">base</a>, <a href="#container_image_-build_context_data">build_context_data</a>, <a href="#container_image_-build_layer">build_layer</a>, <a href="#container_image_-cmd">cmd</a>, <a href="#container_image_-compression">compression</a>,
+                 <a href="#container_image_-compression_options">compression_options</a>, <a href="#container_image_-create_image_config">create_image_config</a>, <a href="#container_image_-creation_time">creation_time</a>, <a href="#container_image_-data_path">data_path</a>, <a href="#container_image_-debs">debs</a>, <a href="#container_image_-directory">directory</a>,
+                 <a href="#container_image_-docker_run_flags">docker_run_flags</a>, <a href="#container_image_-empty_dirs">empty_dirs</a>, <a href="#container_image_-empty_files">empty_files</a>, <a href="#container_image_-enable_mtime_preservation">enable_mtime_preservation</a>, <a href="#container_image_-entrypoint">entrypoint</a>,
+                 <a href="#container_image_-env">env</a>, <a href="#container_image_-experimental_tarball_format">experimental_tarball_format</a>, <a href="#container_image_-extract_config">extract_config</a>, <a href="#container_image_-files">files</a>, <a href="#container_image_-incremental_load_template">incremental_load_template</a>,
                  <a href="#container_image_-label_file_strings">label_file_strings</a>, <a href="#container_image_-label_files">label_files</a>, <a href="#container_image_-labels">labels</a>, <a href="#container_image_-launcher">launcher</a>, <a href="#container_image_-launcher_args">launcher_args</a>, <a href="#container_image_-layers">layers</a>,
                  <a href="#container_image_-legacy_repository_naming">legacy_repository_naming</a>, <a href="#container_image_-legacy_run_behavior">legacy_run_behavior</a>, <a href="#container_image_-mode">mode</a>, <a href="#container_image_-mtime">mtime</a>, <a href="#container_image_-null_cmd">null_cmd</a>,
                  <a href="#container_image_-null_entrypoint">null_entrypoint</a>, <a href="#container_image_-operating_system">operating_system</a>, <a href="#container_image_-os_version">os_version</a>, <a href="#container_image_-portable_mtime">portable_mtime</a>, <a href="#container_image_-ports">ports</a>, <a href="#container_image_-repository">repository</a>,
-                 <a href="#container_image_-sha256">sha256</a>, <a href="#container_image_-stamp">stamp</a>, <a href="#container_image_-symlinks">symlinks</a>, <a href="#container_image_-tars">tars</a>, <a href="#container_image_-user">user</a>, <a href="#container_image_-volumes">volumes</a>, <a href="#container_image_-workdir">workdir</a>)
+                 <a href="#container_image_-sha256">sha256</a>, <a href="#container_image_-symlinks">symlinks</a>, <a href="#container_image_-tars">tars</a>, <a href="#container_image_-user">user</a>, <a href="#container_image_-volumes">volumes</a>, <a href="#container_image_-workdir">workdir</a>)
 </pre>
 
 Called by the `container_image` macro with **kwargs, see below
@@ -29,6 +29,7 @@ Called by the `container_image` macro with **kwargs, see below
 | <a id="container_image_-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required |  |
 | <a id="container_image_-architecture"></a>architecture |  The desired CPU architecture to be used as label in the container image.   | String | optional | "amd64" |
 | <a id="container_image_-base"></a>base |  The base layers on top of which to overlay this layer, equivalent to FROM.   | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
+| <a id="container_image_-build_context_data"></a>build_context_data |  Provides info about the build context, such as stamping.<br><br>By default it reads from the bazel command line, such as the <code>--stamp</code> argument. Use this to override values for this target, such as enabling or disabling stamping. You can use the <code>build_context_data</code> rule from <code>@io_bazel_rules_docker//docker:context.bzl</code> to create a BuildContextInfo and override the --stamp config setting.   | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | @io_bazel_rules_docker//docker:build_context_data |
 | <a id="container_image_-build_layer"></a>build_layer |  -   | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | //container:build_tar |
 | <a id="container_image_-cmd"></a>cmd |  List of commands to execute in the image.<br><br>        See https://docs.docker.com/engine/reference/builder/#cmd<br><br>        The behavior between using <code>""</code> and <code>[]</code> may differ.         Please see [#1448](https://github.com/bazelbuild/rules_docker/issues/1448)         for more details.<br><br>        Set <code>cmd</code> to <code>None</code>, <code>[]</code> or <code>""</code> will set the <code>Cmd</code> of the image to be         <code>null</code>.<br><br>        This field supports stamp variables.   | List of strings | optional | [] |
 | <a id="container_image_-compression"></a>compression |  Compression method for image layer. Currently only gzip is supported.<br><br>        This affects the compressed layer, which is by the <code>container_push</code> rule.         It doesn't affect the layers specified by the <code>layers</code> attribute.   | String | optional | "gzip" |
@@ -66,7 +67,6 @@ Called by the `container_image` macro with **kwargs, see below
 | <a id="container_image_-ports"></a>ports |  List of ports to expose.<br><br>        See https://docs.docker.com/engine/reference/builder/#expose   | List of strings | optional | [] |
 | <a id="container_image_-repository"></a>repository |  The repository for the default tag for the image.<br><br>        Images generated by <code>container_image</code> are tagged by default to         <code>bazel/package_name:target</code> for a <code>container_image</code> target at         <code>//package/name:target</code>.<br><br>        Setting this attribute to <code>gcr.io/dummy</code> would set the default tag to         <code>gcr.io/dummy/package_name:target</code>.   | String | optional | "bazel" |
 | <a id="container_image_-sha256"></a>sha256 |  -   | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | //tools/build_defs/hash:sha256 |
-| <a id="container_image_-stamp"></a>stamp |  If true, enable use of workspace status variables         (e.g. <code>BUILD_USER</code>, <code>BUILD_EMBED_LABEL</code>,         and custom values set using <code>--workspace_status_command</code>)         in tags.<br><br>        These fields are specified in attributes using Python format         syntax, e.g. <code>foo{BUILD_USER}bar</code>.   | Boolean | optional | False |
 | <a id="container_image_-symlinks"></a>symlinks |  Symlinks to create in the Docker image.<br><br>        For example,<br><br>            symlinks = {                 "/path/to/link": "/path/to/target",                 ...             },   | <a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a> | optional | {} |
 | <a id="container_image_-tars"></a>tars |  Tar file to extract in the layer.<br><br>        A list of tar files whose content should be in the Docker image.   | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] |
 | <a id="container_image_-user"></a>user |  The user that the image should run as.<br><br>        See https://docs.docker.com/engine/reference/builder/#user<br><br>        Because building the image never happens inside a Docker container,         this user does not affect the other actions (e.g., adding files).<br><br>        This field supports stamp variables.   | String | optional | "" |