Fix docs for sh_test and sh_binary (#40)

These rules incorrectly shared rule and attr-level docs.

Work towards bazelbuild/bazel#24473

Author: fmeum

shell/private/sh_binary.bzl

@@ -19,4 +19,27 @@ load(":sh_executable.bzl", "make_sh_executable_rule")
 # For doc generation only.
 visibility("public")
 
-sh_binary = make_sh_executable_rule(executable = True)
+sh_binary = make_sh_executable_rule(
+    doc = """
+<p>
+  The <code>sh_binary</code> rule is used to declare executable shell scripts.
+  (<code>sh_binary</code> is a misnomer: its outputs aren't necessarily binaries.) This rule ensures
+  that all dependencies are built, and appear in the <code>runfiles</code> area at execution time.
+  We recommend that you name your <code>sh_binary()</code> rules after the name of the script minus
+  the extension (e.g. <code>.sh</code>); the rule name and the file name must be distinct.
+  <code>sh_binary</code> respects shebangs, so any available interpreter may be used (eg.
+  <code>#!/bin/zsh</code>)
+</p>
+<h4 id="sh_binary_examples">Example</h4>
+<p>For a simple shell script with no dependencies and some data files:
+</p>
+<pre class="code">
+sh_binary(
+    name = "foo",
+    srcs = ["foo.sh"],
+    data = glob(["datafiles/*.txt"]),
+)
+</pre>
+""",
+    executable = True,
+)

shell/private/sh_executable.bzl

@@ -169,39 +169,20 @@ def _launcher_for_windows(ctx, primary_output, main_file):
 
     return _create_windows_exe_launcher(ctx, sh_toolchain, primary_output)
 
-def make_sh_executable_rule(extra_attrs = {}, **kwargs):
+def make_sh_executable_rule(doc, extra_attrs = {}, **kwargs):
     return rule(
         _sh_executable_impl,
-        doc = """
-<p>
-  The <code>sh_binary</code> rule is used to declare executable shell scripts.
-  (<code>sh_binary</code> is a misnomer: its outputs aren't necessarily binaries.) This rule ensures
-  that all dependencies are built, and appear in the <code>runfiles</code> area at execution time.
-  We recommend that you name your <code>sh_binary()</code> rules after the name of the script minus
-  the extension (e.g. <code>.sh</code>); the rule name and the file name must be distinct.
-  <code>sh_binary</code> respects shebangs, so any available interpreter may be used (eg.
-  <code>#!/bin/zsh</code>)
-</p>
-<h4 id="sh_binary_examples">Example</h4>
-<p>For a simple shell script with no dependencies and some data files:
-</p>
-<pre class="code">
-sh_binary(
-    name = "foo",
-    srcs = ["foo.sh"],
-    data = glob(["datafiles/*.txt"]),
-)
-</pre>
-""",
+        doc = doc,
         attrs = {
             "srcs": attr.label_list(
                 allow_files = True,
                 doc = """
-The list of input files.
+The file containing the shell script.
 <p>
-  This attribute should be used to list shell script source files that belong to
-  this library. Scripts can load other scripts using the shell's <code>source</code>
-  or <code>.</code> command.
+  This attribute must be a singleton list, whose element is the shell script.
+  This script must be executable, and may be a source file or a generated file.
+  All other files required at runtime (whether scripts or data) belong in the
+  <code>data</code> attribute.
 </p>
 """,
             ),

shell/private/sh_test.bzl

@@ -20,6 +20,24 @@ load(":sh_executable.bzl", "make_sh_executable_rule")
 visibility("public")
 
 sh_test = make_sh_executable_rule(
+    doc = """
+<p>A <code>sh_test()</code> rule creates a test written as a Bourne shell script.</p>
+
+<p>See the <a href="${link common-definitions#common-attributes-tests}">
+attributes common to all test rules (*_test)</a>.</p>
+
+<h4 id="sh_test_examples">Examples</h4>
+
+<pre class="code">
+sh_test(
+    name = "foo_integration_test",
+    size = "small",
+    srcs = ["foo_integration_test.sh"],
+    deps = [":foo_sh_lib"],
+    data = glob(["testdata/*.txt"]),
+)
+</pre>
+""",
     test = True,
     fragments = ["coverage"],
     extra_attrs = {