docs: add bats docs

README.md

@@ -64,6 +64,10 @@ For example to use commit `abc123`:
 - [stamping](docs/stamping.md) Support version stamping in custom rules.
 - [base64](docs/base64.md) Starlark Base64 encoder & decoder.
 
+## Testing
+
+- [bats_test]:(docs/bats.md) A test runner for the [Bash Automated Testing System](https://github.com/bats-core/bats-core).
+
 ## Generating documentation
 
 - [docs](docs/docs.md) Rules for generating docs and stamping tests to ensure they are up to date.

docs/bats.md

@@ -1,6 +1,26 @@
 <!-- Generated with Stardoc: http://skydoc.bazel.build -->
 
-Bats test runner
+A test rule that invokes the [Bash Automated Testing System](https://github.com/bats-core/bats-core).
+
+For example, a `bats_test` target containing a single .bat and basic configuration:
+
+```starlark
+bats_test(
+    name = "my_test",
+    size = "small",
+    srcs = [
+        "my_test.bats",
+    ],
+    data = [
+        "data.bin",
+    ],
+    env = {
+        "DATA_PATH": "$(location :data.bin)",
+    },
+    args = ["--timing"],
+)
+```
+
 
 <a id="bats_test"></a>
 

lib/bats.bzl

@@ -1,4 +1,24 @@
-"Bats test runner"
+"""A test rule that invokes the [Bash Automated Testing System](https://github.com/bats-core/bats-core).
+
+For example, a `bats_test` target containing a single .bat and basic configuration:
+
+```starlark
+bats_test(
+    name = "my_test",
+    size = "small",
+    srcs = [
+        "my_test.bats",
+    ],
+    data = [
+        "data.bin",
+    ],
+    env = {
+        "DATA_PATH": "$(location :data.bin)",
+    },
+    args = ["--timing"],
+)
+```
+"""
 
 load("//lib/private:bats.bzl", _bats_test = "bats_test")