Merge pull request #10 from chainguard-dev/docs

docs: add cache and rule docs

.gitattributes

@@ -1,3 +1,4 @@
 docs/*.md linguist-generated=true
 docs/initial-setup.md linguist-generated=false
+docs/apko-cache.md linguist-generated=false
 MODULE.bazel.lock linguist-generated=true

apko/BUILD.bazel

@@ -2,7 +2,10 @@ load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
 load("//apko/private:resolved_toolchain.bzl", "resolved_toolchain")
 
 # For stardoc to reference the files
-exports_files(["defs.bzl"])
+exports_files([
+    "defs.bzl",
+    "translate_lock.bzl",
+])
 
 # This is the target rule authors should put in their "toolchains"
 # attribute in order to get a runtime for the correct platform.

apko/private/apko_image.bzl

@@ -1,12 +1,47 @@
 "A rule for running apko with prepopulated cache"
 
+_DOC = """Build OCI images from APK packages directly without Dockerfile
+
+This rule creates Alpine images using the 'apko.yaml' configuration file and relies on cache contents generated by [translate_lock](./translate_lock.md) to be fast.
+
+```starlark
+apko_image(
+    name = "example",
+    config = "apko.yaml",
+    contents = "@example_lock//:contents",
+    tag = "example:latest",
+)
+```
+
+The label `@example_lock//:contents` is generated by the `translate_lock` extension, which consumes an 'apko.lock.json' file. 
+For more details, refer to the [documentation](./docs/apko-cache.md).
+
+An example demonstrating usage with [rules_oci](https://github.com/bazel-contrib/rules_oci)
+
+```starlark
+apko_image(
+    name = "alpine_base",
+    config = "apko.yaml",
+    contents = "@alpine_base_lock//:contents",
+    tag = "alpine_base:latest",
+)
+
+oci_image(
+    name = "app",
+    base = ":alpine_base"
+)
+```
+
+For more examples checkout the [examples](/examples) directory.
+"""
+
 _ATTRS = {
-    "contents": attr.label(mandatory = True),
-    "config": attr.label(allow_single_file = True, mandatory = True),
+    "contents": attr.label(doc = "Label to the contents repository generated by translate_lock. See [apko-cache](./apko-cache.md) documentation.", mandatory = True),
+    "config": attr.label(doc = "Label to the `apko.yaml` file.", allow_single_file = True, mandatory = True),
     "output": attr.string(default = "oci", values = ["oci", "docker"]),
-    "architecture": attr.string(),
-    "tag": attr.string(mandatory = True),
-    "args": attr.string_list(),
+    "architecture": attr.string(doc = "the CPU architecture which this image should be built to run on. See https://github.com/chainguard-dev/apko/blob/main/docs/apko_file.md#archs-top-level-element"),
+    "tag": attr.string(doc = "tag to apply to the resulting docker tarball. only applicable when `output` is `docker`", mandatory = True),
+    "args": attr.string_list(doc = "additional arguments to provide when running the `apko build` command."),
 }
 
 def _impl(ctx):
@@ -61,6 +96,7 @@ def _impl(ctx):
 
 apko_image_lib = struct(
     attrs = _ATTRS,
+    documentation = _DOC,
     implementation = _impl,
     toolchains = ["@rules_apko//apko:toolchain_type"],
 )
@@ -69,4 +105,5 @@ apko_image = rule(
     implementation = apko_image_lib.implementation,
     attrs = apko_image_lib.attrs,
     toolchains = apko_image_lib.toolchains,
+    doc = apko_image_lib.documentation,
 )

apko/translate_lock.bzl

@@ -2,6 +2,11 @@
 
 load("//apko/private:util.bzl", "util")
 
+_DOC = """Repository rule to generate starlark code from an `apko.lock.json` file.
+
+See [apko-cache.md](./apko-cache.md) documentation.
+"""
+
 BUILD_TMPL = """\
 # Generated by apko_translate_lock. DO NOT EDIT.
 filegroup(
@@ -107,7 +112,8 @@ def _translate_apko_lock_impl(rctx):
 translate_apko_lock = repository_rule(
     implementation = _translate_apko_lock_impl,
     attrs = {
-        "lock": attr.label(mandatory = True),
-        "target_name": attr.string(doc = "internal"),
+        "lock": attr.label(doc = "label to the `apko.lock.json` file.", mandatory = True),
+        "target_name": attr.string(doc = "internal. do not use!"),
     },
+    doc = _DOC,
 )

docs/BUILD.bazel

@@ -7,4 +7,9 @@ stardoc_with_diff_test(
     bzl_library_target = "//apko:defs",
 )
 
+stardoc_with_diff_test(
+    name = "translate_lock",
+    bzl_library_target = "//apko:translate_lock",
+)
+
 update_docs(name = "update")

docs/apko-cache.md

@@ -0,0 +1,52 @@
+# Fetching and Caching Contents
+
+To ensure efficient operation, the `apko_image` rule must maintain a cache of remote contents that it fetches from repositories. While outside of Bazel, `apko` manages its own cache, under Bazel, the cache must be maintained by Bazel to ensure correctness and speed. Therefore, Bazel needs to know what needs to be fetched and from where to cache these HTTP requests and provide them to `apko` as required.
+
+The `apko.lock.json` file contains all the necessary information about how to perform the HTTP fetches required by `apko` to build the container image.
+
+## Generating the Lock File
+
+> **Note:** Documentation for lockfile generation will be added once the `apko resolve` command is available.
+
+## Using `translate_lock`
+
+Having just the `apko.lock.json` file alone is insufficient; all the information needs to be converted into `apk_<content_type>` repository calls to make them accessible to Bazel. The `translate_lock` tool accomplishes this by taking the `apko.lock.json` file and dynamically generating the required Bazel repositories.
+
+`translate_lock` will create a new bazel repository named after itself. this repository will also have a target named contents, which you can pass to apko_image:
+
+```starlark
+apko_image(
+    name = "lock",
+    config = "apko.yaml",
+    # name of the repository is the same translate_lock!
+    contents = "@examples_lock//:contents",
+    tag = "lock:latest",
+)
+```
+
+#### Usage with `bzlmod`
+
+```starlark
+apk = use_extension("//apko:extensions.bzl", "apko")
+
+apk.translate_lock(
+    name = "examples_lock",
+    lock = "//path/to/lock:apko.lock.json",
+)
+use_repo(apk, "examples_lock")
+```
+
+#### Usage with Workspace
+
+```starlark
+load("@rules_apko//apko:translate_lock.bzl", "translate_apko_lock")
+
+translate_apko_lock(
+    name = "example_lock",
+    lock = "//path/to/lock:apko.lock.json",
+)
+
+load("@example_lock//:repositories.bzl", "apko_repositories")
+
+apko_repositories()
+```