Use stardoc to automatically generate README.md

BUILD.bazel

@@ -0,0 +1 @@
+exports_files(["README.md"])

README.md

@@ -24,6 +24,8 @@ load("@rules_sh//sh:repositories.bzl", "rules_sh_dependencies")
 rules_sh_dependencies()
 ```
 
+
+
 ## Usage
 
 ### Configure the toolchain
@@ -90,3 +92,5 @@ my_rule = rule(
     ...
 )
 ```
+
+

WORKSPACE

@@ -15,3 +15,19 @@ register_unittest_toolchains()
 load("//tests/import:import_test.bzl", "import_test_repositories")
 
 import_test_repositories()
+
+
+# documentation dependencies
+
+load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+load("@bazel_tools//tools/build_defs/repo:utils.bzl", "maybe")
+
+maybe(
+    http_archive,
+    "io_bazel_stardoc",
+    sha256 = "aa814dae0ac400bbab2e8881f9915c6f47c49664bf087c409a15f90438d2c23e",
+    urls = [
+        "https://mirror.bazel.build/github.com/bazelbuild/stardoc/releases/download/0.5.1/stardoc-0.5.1.tar.gz",
+        "https://github.com/bazelbuild/stardoc/releases/download/0.5.1/stardoc-0.5.1.tar.gz",
+    ],
+)

sh/BUILD.bazel

@@ -21,6 +21,20 @@ bzl_library(
     ],
 )
 
+bzl_library(
+    name = "sh",
+    srcs = [
+        "sh.bzl",
+    ],
+    visibility = ["//visibility:public"],
+    deps = [
+        ":bazel_tools",
+        "@bazel_skylib//lib:paths",
+        "@bazel_skylib//lib:dicts",
+        "//sh/private:defs.bzl"
+    ],
+)
+
 bzl_library(
     name = "posix",
     srcs = [
@@ -32,3 +46,8 @@ bzl_library(
         "@bazel_skylib//lib:paths",
     ],
 )
+
+exports_files([
+    "posix.bzl",
+    "repositories.bzl",
+])

sh/docs/BUILD.bazel

@@ -0,0 +1,55 @@
+load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
+load("@bazel_skylib//rules:diff_test.bzl", "diff_test")
+load("@bazel_skylib//rules:write_file.bzl", "write_file")
+
+stardoc(
+    name = "gen-setup-md",
+    input = "//sh:repositories.bzl",
+    out = "setup.md",
+    deps = ["//sh:repositories"],
+    symbol_names = ["rules_sh_dependencies"],
+    func_template = "//sh/docs:func.vm",
+    header_template = "//sh/docs:header.vm",
+)
+
+stardoc(
+    name = "gen-usage-md",
+    input = "//sh:posix.bzl",
+    out = "usage.md",
+    deps = ["//sh:posix"],
+    symbol_names = ["sh_posix_configure"],
+    func_template = "//sh/docs:func.vm",
+    header_template = "//sh/docs:empty.vm",
+)
+
+genrule(
+    name = "gen-readme-md",
+    outs = ["readme.md"],
+    srcs = [":setup.md", ":usage.md"],
+    cmd = "$(POSIX_CAT) $(execpath :setup.md) $(execpath :usage.md) >$(OUTS)",
+    toolchains = ["@rules_sh//sh/posix:make_variables"],
+)
+
+write_file(
+    name = "write-copy-readme-sh",
+    out = "copy-readme.sh",
+    content = ["""
+        "$POSIX_CP" -v --no-preserve=all "$1" "$BUILD_WORKSPACE_DIRECTORY/README.md"
+    """],
+)
+
+sh_binary(
+    name = "update-readme",
+    srcs = [":copy-readme.sh"],
+    args = ["$(location :readme.md)"],
+    data = [":readme.md"],
+    env = {"POSIX_CP": "$(POSIX_CP)"},
+    toolchains = ["@rules_sh//sh/posix:make_variables"],
+)
+
+diff_test(
+    name = "check-readme",
+    failure_message = "Please run: bazel run //sh/docs:update-readme",
+    file1 = "//:README.md",
+    file2 = ":readme.md",
+)

sh/docs/func.vm

@@ -0,0 +1 @@
+${funcInfo.docString}

sh/docs/header.vm

@@ -0,0 +1,3 @@
+# Shell rules for Bazel
+
+This project extends Bazel with a toolchain for common shell commands.

sh/posix.bzl

@@ -347,14 +347,72 @@ _sh_posix_config = repository_rule(
 )
 
 def sh_posix_configure(name = "local_posix_config", register = True):
-    """Autodetect local Unix commands.
+    """## Usage
 
-    Scans the environment (`$PATH`) for standard shell commands, generates a
-    corresponding POSIX toolchain and registers the toolchain.
+    ### Configure the toolchain
 
-    You can override the autodetection for individual commands by setting
-    environment variables of the form `POSIX_<COMMAND>`. E.g.
-    `POSIX_MAKE=/usr/bin/gmake` will override the make command.
+    Add the following to your `WORKSPACE` file to configure a local POSIX toolchain.
+
+    ``` python
+    load("@rules_sh//sh:posix.bzl", "sh_posix_configure")
+    sh_posix_configure()
+    ```
+
+    Bazel will query `PATH` for common Unix shell commands. You can override the
+    path to individual commands with environment variables of the form
+    `POSIX_<COMMAND_NAME>`. E.g. `POSIX_MAKE=/usr/bin/gmake`.
+
+    Note, this introduces an inhermeticity to the build as the contents of `PATH`
+    may be specific to your machine's setup.
+
+    Refer to [`rules_nixpkgs`'s][rules_nixpkgs] `nixpkgs_posix_configure` for a
+    hermetic alternative.
+
+    [rules_nixpkgs]: https://github.com/tweag/rules_nixpkgs.git
+
+    ### Use Unix tools in `genrule`s
+
+    The POSIX toolchain exposes custom make variables of the form
+    `POSIX_<COMMAND_NAME>` for discovered commands. Use these as follows:
+
+    ``` python
+    genrule(
+        name = "example",
+        srcs = [":some-input-file"],
+        outs = ["some-output-file"],
+        cmd = "$(POSIX_GREP) some-pattern $(execpath :some-input-file.bzl) > $(OUTS)",
+        toolchains = ["@rules_sh//sh/posix:make_variables"],
+    )
+    ```
+
+    See `posix.commands` defined in `@rules_sh//sh/posix.bzl` for the list of known
+    POSIX commands.
+
+    ### Use Unix tools in custom rules
+
+    The POSIX toolchain provides two attributes:
+    - `commands`: A `dict` mapping names of commands to their paths.
+    - `paths`: A deduplicated list of bindir paths suitable for generating `$PATH`.
+
+    ``` python
+    def _my_rule_impl(ctx):
+        posix_info = ctx.toolchains["@rules_sh//sh/posix:toolchain_type"]
+        ctx.actions.run(
+            executable = posix_info.commands["grep"],
+            ...
+        )
+        ctx.actions.run_shell(
+            command = "grep ...",
+            env = {"PATH": ":".join(posix_info.paths)},
+            ...
+        )
+
+    my_rule = rule(
+        _my_rule_impl,
+        toolchains = ["@rules_sh//sh/posix:toolchain_type"],
+        ...
+    )
+    ```
     """
     _sh_posix_config(name = name)
     if register:

sh/private/BUILD.bazel

@@ -8,3 +8,5 @@ bool_constant(
     }),
     visibility = ["//visibility:public"],
 )
+
+exports_files(["defs.bzl"])

sh/repositories.bzl

@@ -2,13 +2,34 @@ load("@bazel_tools//tools/build_defs/repo:utils.bzl", "maybe")
 load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive", "http_file")
 
 def rules_sh_dependencies():
-    """Load repositories required by rules_sh."""
+    """## Setup
+
+    See the **WORKSPACE setup** section of the [current release][releases].
+
+    [releases]: https://github.com/tweag/rules_sh/releases
+
+    Or use the following template in your `WORKSPACE` file to install a development
+    version of `rules_sh`:
+
+    ``` python
+    load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+    http_archive(
+        name = "rules_sh",
+        # Replace git revision and sha256.
+        sha256 = "0000000000000000000000000000000000000000000000000000000000000000",
+        strip_prefix = "rules_sh-0000000000000000000000000000000000000000",
+        urls = ["https://github.com/tweag/rules_sh/archive/0000000000000000000000000000000000000000.tar.gz"],
+    )
+    load("@rules_sh//sh:repositories.bzl", "rules_sh_dependencies")
+    rules_sh_dependencies()
+    ```
+    """
     maybe(
         http_archive,
         name = "bazel_skylib",
-        sha256 = "e5d90f0ec952883d56747b7604e2a15ee36e288bb556c3d0ed33e818a4d971f2",
-        strip_prefix = "bazel-skylib-1.0.2",
-        urls = ["https://github.com/bazelbuild/bazel-skylib/archive/1.0.2.tar.gz"],
+        sha256 = "710c2ca4b4d46250cdce2bf8f5aa76ea1f0cba514ab368f2988f70e864cfaf51",
+        strip_prefix = "bazel-skylib-1.2.1",
+        urls = ["https://github.com/bazelbuild/bazel-skylib/archive/1.2.1.tar.gz"],
     )
     maybe(
         http_archive,