fix docs

aspect-build · Oct 4, 2024 · 7880085 · 7880085
1 parent 9252e7d
commit 7880085
Show file tree

Hide file tree

Showing 3 changed files with 55 additions and 69 deletions.
diff --git a/docs/BUILD.bazel b/docs/BUILD.bazel
@@ -33,10 +33,7 @@ stardoc_with_diff_test(
 
 stardoc_with_diff_test(
     name = "py_image_layer",
-    bzl_library_target = "//py:defs",
-    symbol_names = [
-        "py_image_layer",
-    ],
+    bzl_library_target = "//py/private:py_image_layer",
 )
 
 stardoc_with_diff_test(

diff --git a/docs/py_image_layer.md b/docs/py_image_layer.md
diff --git a/py/private/py_image_layer.bzl b/py/private/py_image_layer.bzl
@@ -1,4 +1,34 @@
-"py_image_layer"
+"""py_image_layer macro for creating multiple layers from a py_binary
+
+>> [!WARNING]
+>> This macro is EXPERIMENTAL and is not subject to our SemVer guarantees.
+
+A py_binary that uses `torch` and `numpy` can use the following layer groups:
+
+```
+load("@rules_oci//oci:defs.bzl", "oci_image")
+load("@aspect_rules_py//py:defs.bzl", "py_image_layer", "py_binary")
+
+py_binary(
+    name = "my_app_bin",
+    deps = [
+        "@pip_deps//numpy",
+        "@pip_deps//torch"
+    ]
+)
+
+oci_image(
+    tars = py_image_layer(
+        name = "my_app",
+        py_binary = ":my_app_bin",
+        layer_groups = {
+            "torch": "pip_deps_torch.*",
+            "numpy": "pip_deps_numpy.*",
+        }
+    )
+)
+```
+"""
 
 load("@aspect_bazel_lib//lib:tar.bzl", "mtree_spec", "tar")
 
@@ -63,8 +93,6 @@ awk < $< 'BEGIN {
 def py_image_layer(name, py_binary, root = None, layer_groups = {}, compress = "gzip", tar_args = ["--options", "gzip:!timestamp"], **kwargs):
     """Produce a separate tar output for each layer of a python app
 
-    > Note: This macro is EXPERIMENTAL and is not subject to our SemVer guarantees.
-
     > Requires `awk` to be installed on the host machine/rbe runner.
 
     For better performance, it is recommended to split the output of a py_binary into multiple layers.
@@ -83,22 +111,6 @@ def py_image_layer(name, py_binary, root = None, layer_groups = {}, compress = "
     }
     ```
 
-    A py_binary that uses `torch` and `numpy` can use the following layer groups:
-
-    ```
-    oci_image(
-        tars = py_image_layer(
-            name = "my_app",
-            py_binary = ":my_app_bin",
-            layer_groups = {
-                "torch": "pip_deps_torch.*",
-                "numpy": "pip_deps_numpy.*",
-            }
-        )
-    )
-    ```
-    
-
     Args:
         name: base name for targets
         py_binary: a py_binary target