feat: add docs

.github/workflows/BUILD.bazel

@@ -1,3 +1,6 @@
 package(default_visibility = ["//visibility:public"])
 
-exports_files(["ci.yml"])
+exports_files([
+    "ci.yml",
+    "pages.yml",
+])

.github/workflows/pages.yml

@@ -0,0 +1,51 @@
+name: Docs Pages
+
+on:
+  push:
+    branches: ["main"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    env:
+      USE_BAZEL_VERSION: 9.0.0
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: bazel-contrib/setup-bazel@0.15.0
+
+      - name: Generate rule docs
+        run: |
+          bazel build //docs:rules_md
+          cp bazel-bin/docs/rules.md docs/rules.md
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Build with Jekyll
+        uses: actions/jekyll-build-pages@v1
+        with:
+          source: docs
+          destination: _site
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: _site
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

MODULE.bazel

@@ -5,14 +5,16 @@ module(
 
 bazel_dep(name = "platforms", version = "1.0.0")
 bazel_dep(name = "rules_shell", version = "0.6.1")
+bazel_dep(name = "bazel_skylib", version = "1.8.0")
+bazel_dep(name = "stardoc", version = "0.7.1")
 
 bun_ext = use_extension("//bun:extensions.bzl", "bun")
 use_repo(
     bun_ext,
-    "bun_linux_x64",
-    "bun_linux_aarch64",
-    "bun_darwin_x64",
     "bun_darwin_aarch64",
+    "bun_darwin_x64",
+    "bun_linux_aarch64",
+    "bun_linux_x64",
     "bun_windows_x64",
 )
 

MODULE.bazel.lock

@@ -48,6 +48,7 @@
     "https://bcr.bazel.build/modules/bazel_skylib/1.6.1/MODULE.bazel": "8fdee2dbaace6c252131c00e1de4b165dc65af02ea278476187765e1a617b917",
     "https://bcr.bazel.build/modules/bazel_skylib/1.7.0/MODULE.bazel": "0db596f4563de7938de764cc8deeabec291f55e8ec15299718b93c4423e9796d",
     "https://bcr.bazel.build/modules/bazel_skylib/1.7.1/MODULE.bazel": "3120d80c5861aa616222ec015332e5f8d3171e062e3e804a2a0253e1be26e59b",
+    "https://bcr.bazel.build/modules/bazel_skylib/1.8.0/MODULE.bazel": "2fb3fb53675f6adfc1ca5bfbd5cfb655ae350fba4706d924a8ec7e3ba945671c",
     "https://bcr.bazel.build/modules/bazel_skylib/1.8.1/MODULE.bazel": "88ade7293becda963e0e3ea33e7d54d3425127e0a326e0d17da085a5f1f03ff6",
     "https://bcr.bazel.build/modules/bazel_skylib/1.8.2/MODULE.bazel": "69ad6927098316848b34a9142bcc975e018ba27f08c4ff403f50c1b6e646ca67",
     "https://bcr.bazel.build/modules/bazel_skylib/1.8.2/source.json": "34a3c8bcf233b835eb74be9d628899bb32999d3e0eadef1947a0a562a2b16ffb",
@@ -119,10 +120,13 @@
     "https://bcr.bazel.build/modules/rules_fuzzing/0.5.2/MODULE.bazel": "40c97d1144356f52905566c55811f13b299453a14ac7769dfba2ac38192337a8",
     "https://bcr.bazel.build/modules/rules_java/4.0.0/MODULE.bazel": "5a78a7ae82cd1a33cef56dc578c7d2a46ed0dca12643ee45edbb8417899e6f74",
     "https://bcr.bazel.build/modules/rules_java/5.3.5/MODULE.bazel": "a4ec4f2db570171e3e5eb753276ee4b389bae16b96207e9d3230895c99644b86",
+    "https://bcr.bazel.build/modules/rules_java/6.0.0/MODULE.bazel": "8a43b7df601a7ec1af61d79345c17b31ea1fedc6711fd4abfd013ea612978e39",
+    "https://bcr.bazel.build/modules/rules_java/6.4.0/MODULE.bazel": "e986a9fe25aeaa84ac17ca093ef13a4637f6107375f64667a15999f77db6c8f6",
     "https://bcr.bazel.build/modules/rules_java/6.5.2/MODULE.bazel": "1d440d262d0e08453fa0c4d8f699ba81609ed0e9a9a0f02cd10b3e7942e61e31",
     "https://bcr.bazel.build/modules/rules_java/7.10.0/MODULE.bazel": "530c3beb3067e870561739f1144329a21c851ff771cd752a49e06e3dc9c2e71a",
     "https://bcr.bazel.build/modules/rules_java/7.12.2/MODULE.bazel": "579c505165ee757a4280ef83cda0150eea193eed3bef50b1004ba88b99da6de6",
     "https://bcr.bazel.build/modules/rules_java/7.2.0/MODULE.bazel": "06c0334c9be61e6cef2c8c84a7800cef502063269a5af25ceb100b192453d4ab",
+    "https://bcr.bazel.build/modules/rules_java/7.3.2/MODULE.bazel": "50dece891cfdf1741ea230d001aa9c14398062f2b7c066470accace78e412bc2",
     "https://bcr.bazel.build/modules/rules_java/7.6.1/MODULE.bazel": "2f14b7e8a1aa2f67ae92bc69d1ec0fa8d9f827c4e17ff5e5f02e91caa3b2d0fe",
     "https://bcr.bazel.build/modules/rules_java/8.3.2/MODULE.bazel": "7336d5511ad5af0b8615fdc7477535a2e4e723a357b6713af439fe8cf0195017",
     "https://bcr.bazel.build/modules/rules_java/8.5.1/MODULE.bazel": "d8a9e38cc5228881f7055a6079f6f7821a073df3744d441978e7a43e20226939",
@@ -132,9 +136,12 @@
     "https://bcr.bazel.build/modules/rules_jvm_external/4.4.2/MODULE.bazel": "a56b85e418c83eb1839819f0b515c431010160383306d13ec21959ac412d2fe7",
     "https://bcr.bazel.build/modules/rules_jvm_external/5.1/MODULE.bazel": "33f6f999e03183f7d088c9be518a63467dfd0be94a11d0055fe2d210f89aa909",
     "https://bcr.bazel.build/modules/rules_jvm_external/5.2/MODULE.bazel": "d9351ba35217ad0de03816ef3ed63f89d411349353077348a45348b096615036",
+    "https://bcr.bazel.build/modules/rules_jvm_external/5.3/MODULE.bazel": "bf93870767689637164657731849fb887ad086739bd5d360d90007a581d5527d",
+    "https://bcr.bazel.build/modules/rules_jvm_external/6.1/MODULE.bazel": "75b5fec090dbd46cf9b7d8ea08cf84a0472d92ba3585b476f44c326eda8059c4",
     "https://bcr.bazel.build/modules/rules_jvm_external/6.3/MODULE.bazel": "c998e060b85f71e00de5ec552019347c8bca255062c990ac02d051bb80a38df0",
     "https://bcr.bazel.build/modules/rules_jvm_external/6.7/MODULE.bazel": "e717beabc4d091ecb2c803c2d341b88590e9116b8bf7947915eeb33aab4f96dd",
     "https://bcr.bazel.build/modules/rules_jvm_external/6.7/source.json": "5426f412d0a7fc6b611643376c7e4a82dec991491b9ce5cb1cfdd25fe2e92be4",
+    "https://bcr.bazel.build/modules/rules_kotlin/1.9.0/MODULE.bazel": "ef85697305025e5a61f395d4eaede272a5393cee479ace6686dba707de804d59",
     "https://bcr.bazel.build/modules/rules_kotlin/1.9.6/MODULE.bazel": "d269a01a18ee74d0335450b10f62c9ed81f2321d7958a2934e44272fe82dcef3",
     "https://bcr.bazel.build/modules/rules_kotlin/1.9.6/source.json": "2faa4794364282db7c06600b7e5e34867a564ae91bda7cae7c29c64e9466b7d5",
     "https://bcr.bazel.build/modules/rules_license/0.0.3/MODULE.bazel": "627e9ab0247f7d1e05736b59dbb1b6871373de5ad31c3011880b4133cafd4bd0",
@@ -173,7 +180,9 @@
     "https://bcr.bazel.build/modules/rules_swift/3.1.2/source.json": "e85761f3098a6faf40b8187695e3de6d97944e98abd0d8ce579cb2daf6319a66",
     "https://bcr.bazel.build/modules/stardoc/0.5.1/MODULE.bazel": "1a05d92974d0c122f5ccf09291442580317cdd859f07a8655f1db9a60374f9f8",
     "https://bcr.bazel.build/modules/stardoc/0.5.3/MODULE.bazel": "c7f6948dae6999bf0db32c1858ae345f112cacf98f174c7a8bb707e41b974f1c",
+    "https://bcr.bazel.build/modules/stardoc/0.5.6/MODULE.bazel": "c43dabc564990eeab55e25ed61c07a1aadafe9ece96a4efabb3f8bf9063b71ef",
     "https://bcr.bazel.build/modules/stardoc/0.7.0/MODULE.bazel": "05e3d6d30c099b6770e97da986c53bd31844d7f13d41412480ea265ac9e8079c",
+    "https://bcr.bazel.build/modules/stardoc/0.7.1/MODULE.bazel": "3548faea4ee5dda5580f9af150e79d0f6aea934fc60c1cc50f4efdd9420759e7",
     "https://bcr.bazel.build/modules/stardoc/0.7.2/MODULE.bazel": "fc152419aa2ea0f51c29583fab1e8c99ddefd5b3778421845606ee628629e0e5",
     "https://bcr.bazel.build/modules/stardoc/0.7.2/source.json": "58b029e5e901d6802967754adf0a9056747e8176f017cfe3607c0851f4d42216",
     "https://bcr.bazel.build/modules/swift_argument_parser/1.3.1.1/MODULE.bazel": "5e463fbfba7b1701d957555ed45097d7f984211330106ccd1352c6e0af0dcf91",

README.md

@@ -2,6 +2,11 @@
 
 Bazel rules for bun.
 
+## Rule reference
+
+- Generated API docs: [docs/rules.md](docs/rules.md)
+- Regenerate: `bazel build //docs:rules_md && cp bazel-bin/docs/rules.md docs/rules.md`
+
 ## Use
 
 These steps show how to consume a tagged release of `rules_bun` in a separate Bazel workspace.

bun/BUILD.bazel

@@ -1,3 +1,4 @@
+load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
 load(":toolchain.bzl", "bun_toolchain")
 load(":version.bzl", "BUN_VERSION")
 
@@ -6,6 +7,26 @@ exports_files([
     "extensions.bzl",
 ])
 
+bzl_library(
+    name = "toolchain_bzl",
+    srcs = ["toolchain.bzl"],
+    visibility = ["//visibility:public"],
+)
+
+bzl_library(
+    name = "defs_bzl",
+    srcs = ["defs.bzl"],
+    visibility = ["//visibility:public"],
+    deps = [
+        ":toolchain_bzl",
+        "//internal:bun_binary_bzl",
+        "//internal:bun_bundle_bzl",
+        "//internal:bun_dev_bzl",
+        "//internal:bun_test_bzl",
+        "//internal:js_library_bzl",
+    ],
+)
+
 toolchain_type(name = "toolchain_type")
 
 bun_toolchain(

docs/BUILD.bazel

@@ -0,0 +1,18 @@
+load("@stardoc//stardoc:stardoc.bzl", "stardoc")
+
+package(default_visibility = ["//visibility:public"])
+
+stardoc(
+    name = "rules_md",
+    out = "rules.md",
+    input = "//bun:defs.bzl",
+    symbol_names = [
+        "bun_binary",
+        "bun_bundle",
+        "bun_dev",
+        "bun_test",
+        "js_library",
+        "ts_library",
+    ],
+    deps = ["//bun:defs_bzl"],
+)

docs/index.md

@@ -0,0 +1,16 @@
+# rules_bun docs
+
+Documentation site for `rules_bun`.
+
+## Rule reference
+
+- [rules.md](rules.md)
+
+## Regeneration
+
+The rule reference is generated from Starlark rule docstrings:
+
+```bash
+bazel build //docs:rules_md
+cp bazel-bin/docs/rules.md docs/rules.md
+```

docs/rules.md

@@ -0,0 +1,72 @@
+# rules_bun rule reference
+
+This file documents the public rules exported from `@rules_bun//bun:defs.bzl`.
+
+## bun_binary
+
+Runs a JS/TS entry point with Bun as an executable target (`bazel run`).
+
+Attributes:
+
+- `entry_point` (label, required): path to the main JS/TS file to execute.
+- `node_modules` (label, optional): Bun/npm package files in runfiles.
+- `data` (label_list, optional): additional runtime files.
+- `working_dir` (string, default: `"workspace"`, values: `"workspace" | "entry_point"`): runtime working directory.
+
+## bun_dev
+
+Runs a JS/TS entry point in Bun development watch mode (`bazel run`).
+
+Attributes:
+
+- `entry_point` (label, required): path to the main JS/TS file.
+- `watch_mode` (string, default: `"watch"`, values: `"watch" | "hot"`): Bun live-reload mode.
+- `restart_on` (label_list, optional): files that trigger full process restart when changed.
+- `node_modules` (label, optional): Bun/npm package files in runfiles.
+- `data` (label_list, optional): additional runtime files for dev process.
+- `working_dir` (string, default: `"workspace"`, values: `"workspace" | "entry_point"`): runtime working directory.
+
+## bun_bundle
+
+Bundles one or more JS/TS entry points with Bun build.
+
+Attributes:
+
+- `entry_points` (label_list, required): entry files to bundle.
+- `node_modules` (label, optional): Bun/npm package files for resolution.
+- `deps` (label_list, optional): source/library dependencies for transitive inputs.
+- `data` (label_list, optional): additional non-source files needed during bundling.
+- `target` (string, default: `"browser"`, values: `"browser" | "node" | "bun"`): Bun build target.
+- `format` (string, default: `"esm"`, values: `"esm" | "cjs" | "iife"`): module format.
+- `minify` (bool, default: `False`): minifies bundle output.
+- `sourcemap` (bool, default: `False`): emits source maps.
+- `external` (string_list, optional): package names treated as external (not bundled).
+
+## bun_test
+
+Runs Bun tests as a Bazel test target (`bazel test`).
+
+Attributes:
+
+- `srcs` (label_list, required): test source files passed to `bun test`.
+- `node_modules` (label, optional): Bun/npm package files in runfiles.
+- `deps` (label_list, optional): library dependencies required by tests.
+- `data` (label_list, optional): additional runtime files needed by tests.
+
+## js_library
+
+Aggregates JavaScript sources and transitive Bun source dependencies.
+
+Attributes:
+
+- `srcs` (label_list, optional): `.js`, `.jsx`, `.mjs`, `.cjs` files.
+- `deps` (label_list, optional): dependent source libraries.
+
+## ts_library
+
+Aggregates TypeScript sources and transitive Bun source dependencies.
+
+Attributes:
+
+- `srcs` (label_list, optional): `.ts`, `.tsx` files.
+- `deps` (label_list, optional): dependent source libraries.

internal/BUILD.bazel

@@ -1,10 +1,39 @@
+load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
+
 package(default_visibility = ["//visibility:public"])
 
 exports_files([
-	"bun_binary.bzl",
+    "bun_binary.bzl",
-	"bun_bundle.bzl",
+    "bun_bundle.bzl",
-	"bun_dev.bzl",
+    "bun_dev.bzl",
-	"bun_install.bzl",
+    "bun_install.bzl",
-	"bun_test.bzl",
+    "bun_test.bzl",
-	"js_library.bzl",
+    "js_library.bzl",
 ])
+
+bzl_library(
+    name = "bun_binary_bzl",
+    srcs = ["bun_binary.bzl"],
+)
+
+bzl_library(
+    name = "bun_bundle_bzl",
+    srcs = ["bun_bundle.bzl"],
+    deps = [":js_library_bzl"],
+)
+
+bzl_library(
+    name = "bun_dev_bzl",
+    srcs = ["bun_dev.bzl"],
+)
+
+bzl_library(
+    name = "bun_test_bzl",
+    srcs = ["bun_test.bzl"],
+    deps = [":js_library_bzl"],
+)
+
+bzl_library(
+    name = "js_library_bzl",
+    srcs = ["js_library.bzl"],
+)

internal/bun_binary.bzl

@@ -51,16 +51,27 @@ exec "${{bun_bin}}" --bun run "${{entry_point}}" "$@"
 
 bun_binary = rule(
     implementation = _bun_binary_impl,
+    doc = """Runs a JS/TS entry point with Bun as an executable target.
+
+Use this rule for non-test scripts and CLIs that should run via `bazel run`.
+""",
     attrs = {
         "entry_point": attr.label(
             mandatory = True,
             allow_single_file = [".js", ".ts", ".jsx", ".tsx", ".mjs", ".cjs"],
+            doc = "Path to the main JS/TS file to execute.",
+        ),
+        "node_modules": attr.label(
+            doc = "Optional label providing Bun/npm package files in runfiles.",
+        ),
+        "data": attr.label_list(
+            allow_files = True,
+            doc = "Additional runtime files required by the program.",
         ),
-        "node_modules": attr.label(),
-        "data": attr.label_list(allow_files = True),
         "working_dir": attr.string(
             default = "workspace",
             values = ["workspace", "entry_point"],
+            doc = "Working directory at runtime: `workspace` root or `entry_point` directory.",
         ),
     },
     executable = True,

internal/bun_bundle.bzl

@@ -61,25 +61,47 @@ def _bun_bundle_impl(ctx):
 
 bun_bundle = rule(
     implementation = _bun_bundle_impl,
+    doc = """Bundles one or more JS/TS entry points using Bun build.
+
+Each entry point produces one output JavaScript artifact.
+""",
     attrs = {
         "entry_points": attr.label_list(
             mandatory = True,
             allow_files = [".js", ".ts", ".jsx", ".tsx", ".mjs", ".cjs"],
+            doc = "Entry files to bundle.",
+        ),
+        "node_modules": attr.label(
+            doc = "Optional label providing Bun/npm package files for resolution.",
+        ),
+        "deps": attr.label_list(
+            doc = "Source/library dependencies that provide transitive inputs.",
+        ),
+        "data": attr.label_list(
+            allow_files = True,
+            doc = "Additional non-source files needed during bundling.",
         ),
-        "node_modules": attr.label(),
-        "deps": attr.label_list(),
-        "data": attr.label_list(allow_files = True),
         "target": attr.string(
             default = "browser",
             values = ["browser", "node", "bun"],
+            doc = "Bun build target environment.",
         ),
         "format": attr.string(
             default = "esm",
             values = ["esm", "cjs", "iife"],
+            doc = "Output module format.",
+        ),
+        "minify": attr.bool(
+            default = False,
+            doc = "If true, minifies bundle output.",
+        ),
+        "sourcemap": attr.bool(
+            default = False,
+            doc = "If true, emits source maps.",
+        ),
+        "external": attr.string_list(
+            doc = "Package names to treat as externals (not bundled).",
         ),
-        "minify": attr.bool(default = False),
-        "sourcemap": attr.bool(default = False),
-        "external": attr.string_list(),
     },
     toolchains = ["//bun:toolchain_type"],
 )

internal/bun_dev.bzl

@@ -131,21 +131,37 @@ done
 
 bun_dev = rule(
     implementation = _bun_dev_impl,
+    doc = """Runs a JS/TS entry point in Bun development watch mode.
+
+This rule is intended for local dev loops (`bazel run`) and supports Bun
+watch/HMR plus optional full restarts on selected file changes.
+""",
     attrs = {
         "entry_point": attr.label(
             mandatory = True,
             allow_single_file = [".js", ".ts", ".jsx", ".tsx", ".mjs", ".cjs"],
+            doc = "Path to the main JS/TS file to execute in dev mode.",
         ),
         "watch_mode": attr.string(
             default = "watch",
             values = ["watch", "hot"],
+            doc = "Bun live-reload mode: `watch` (default) or `hot`.",
+        ),
+        "restart_on": attr.label_list(
+            allow_files = True,
+            doc = "Files that trigger a full Bun process restart when they change.",
+        ),
+        "node_modules": attr.label(
+            doc = "Optional label providing Bun/npm package files in runfiles.",
+        ),
+        "data": attr.label_list(
+            allow_files = True,
+            doc = "Additional runtime files required by the dev process.",
         ),
-        "restart_on": attr.label_list(allow_files = True),
-        "node_modules": attr.label(),
-        "data": attr.label_list(allow_files = True),
         "working_dir": attr.string(
             default = "workspace",
             values = ["workspace", "entry_point"],
+            doc = "Working directory at runtime: `workspace` root or `entry_point` directory.",
         ),
     },
     executable = True,

internal/bun_test.bzl

@@ -63,14 +63,26 @@ exec "${{bun_bin}}" --bun test {src_args} "$@"
 
 bun_test = rule(
     implementation = _bun_test_impl,
+    doc = """Runs Bun tests as a Bazel test target.
+
+Supports Bazel test filtering (`--test_filter`) and coverage integration.
+""",
     attrs = {
         "srcs": attr.label_list(
             mandatory = True,
             allow_files = [".js", ".ts", ".jsx", ".tsx", ".mjs", ".cjs"],
+            doc = "Test source files passed to `bun test`.",
+        ),
+        "node_modules": attr.label(
+            doc = "Optional label providing Bun/npm package files in runfiles.",
+        ),
+        "deps": attr.label_list(
+            doc = "Library dependencies required by test sources.",
+        ),
+        "data": attr.label_list(
+            allow_files = True,
+            doc = "Additional runtime files needed by tests.",
         ),
-        "node_modules": attr.label(),
-        "deps": attr.label_list(),
-        "data": attr.label_list(allow_files = True),
     },
     test = True,
     toolchains = ["//bun:toolchain_type"],

internal/js_library.bzl

@@ -21,20 +21,28 @@ def _bun_library_impl(ctx):
 
 js_library = rule(
     implementation = _bun_library_impl,
+    doc = "Aggregates JavaScript sources and transitive Bun source dependencies.",
     attrs = {
         "srcs": attr.label_list(
             allow_files = [".js", ".jsx", ".mjs", ".cjs"],
+            doc = "JavaScript source files in this library.",
+        ),
+        "deps": attr.label_list(
+            doc = "Other Bun source libraries to include transitively.",
         ),
-        "deps": attr.label_list(),
     },
 )
 
 ts_library = rule(
     implementation = _bun_library_impl,
+    doc = "Aggregates TypeScript sources and transitive Bun source dependencies.",
     attrs = {
         "srcs": attr.label_list(
             allow_files = [".ts", ".tsx"],
+            doc = "TypeScript source files in this library.",
+        ),
+        "deps": attr.label_list(
+            doc = "Other Bun source libraries to include transitively.",
         ),
-        "deps": attr.label_list(),
     },
 )