chore: produce bazel docs (#364)

Author: alexeagle

.bazelrc

@@ -0,0 +1 @@
+common --enable_bzlmod

BUILD.bazel

@@ -1 +1,11 @@
-# Marker that this is the root of a Bazel package
+load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
+
+# For stardoc to reference the file directly
+exports_files(["defs.bzl"])
+
+bzl_library(
+    name = "defs",
+    srcs = ["defs.bzl"],
+    deps = ["//bazel:container_structure_test"],
+    visibility = ["//visibility:public"],
+)

MODULE.bazel

@@ -15,3 +15,6 @@ ext = use_extension("//:repositories.bzl", "extension")
 use_repo(ext, "structure_test_toolchains")
 
 register_toolchains("@structure_test_toolchains//:all")
+
+# 0.5.4 is the first version with bzlmod support
+bazel_dep(name = "stardoc", version = "0.5.4", repo_name = "io_bazel_stardoc")

bazel/BUILD.bazel

@@ -1,4 +1,16 @@
+load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
+
+package(default_visibility = ["//visibility:public"])
+
 toolchain_type(
     name = "structure_test_toolchain_type",
-    visibility = ["//visibility:public"],
-)
+)
+
+bzl_library(
+    name = "container_structure_test",
+    srcs = ["container_structure_test.bzl"],
+    deps = [
+        "@aspect_bazel_lib//lib:paths",
+        "@aspect_bazel_lib//lib:windows_utils",
+    ],
+)

bazel/docs/BUILD.bazel

@@ -0,0 +1,10 @@
+# This load statement must be in the docs/ package rather than anything users depend on
+# so that the dependency on stardoc doesn't leak to them.
+load("@aspect_bazel_lib//lib:docs.bzl", "stardoc_with_diff_test", "update_docs")
+
+stardoc_with_diff_test(
+    name = "defs",
+    bzl_library_target = "//:defs",
+)
+
+update_docs(name = "update")

bazel/docs/defs.md

@@ -0,0 +1,38 @@
+<!-- Generated with Stardoc: http://skydoc.bazel.build -->
+
+Exposes container-structure-test as a Bazel rule
+
+<a id="container_structure_test"></a>
+
+## container_structure_test
+
+<pre>
+container_structure_test(<a href="#container_structure_test-name">name</a>, <a href="#container_structure_test-configs">configs</a>, <a href="#container_structure_test-driver">driver</a>, <a href="#container_structure_test-image">image</a>)
+</pre>
+
+Tests a Docker- or OCI-format image.
+
+By default, it relies on the container runtime already installed and running on the target.
+
+By default, container-structure-test uses the socket available at `/var/run/docker.sock`.
+If the installation creates the socket in a different path, use
+`--test_env=DOCKER_HOST='unix://&lt;path_to_sock&gt;'`.
+
+To avoid putting this into the commandline or to instruct bazel to read it from terminal environment, 
+simply add `test --test_env=DOCKER_HOST` into the `.bazelrc` file.
+
+Alternatively, use the `driver = "tar"` attribute to avoid the need for a container runtime, see
+https://github.com/GoogleContainerTools/container-structure-test#running-file-tests-without-docker
+
+
+**ATTRIBUTES**
+
+
+| Name  | Description | Type | Mandatory | Default |
+| :------------- | :------------- | :------------- | :------------- | :------------- |
+| <a id="container_structure_test-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |  |
+| <a id="container_structure_test-configs"></a>configs |  -   | <a href="https://bazel.build/concepts/labels">List of labels</a> | required |  |
+| <a id="container_structure_test-driver"></a>driver |  See https://github.com/GoogleContainerTools/container-structure-test#running-file-tests-without-docker   | String | optional | <code>"docker"</code> |
+| <a id="container_structure_test-image"></a>image |  Label of an oci_image or oci_tarball target.   | <a href="https://bazel.build/concepts/labels">Label</a> | optional | <code>None</code> |
+
+