rules_python_external: fill missing docstrings (#358)

add missing docstrings for rules_python_external

also remove unused attr on pip_repository repo rule

Author: Jonathon Belotti

experimental/rules_python_external/defs.bzl

@@ -91,16 +91,94 @@ use this attribute to specify its BUILD target. This allows pip_repository to in
 pip using the same interpreter as your toolchain. If set, takes precedence over
 python_interpreter.
 """),
-        "quiet": attr.bool(default = True),
-        "requirements": attr.label(allow_single_file = True, mandatory = True),
+        "quiet": attr.bool(
+            default = True,
+            doc = "If True, suppress printing stdout and stderr output to the terminal.",
+        ),
+        "requirements": attr.label(
+            allow_single_file = True,
+            mandatory = True,
+            doc = "A 'requirements.txt' pip requirements file.",
+        ),
         # 600 is documented as default here: https://docs.bazel.build/versions/master/skylark/lib/repository_ctx.html#execute
-        "timeout": attr.int(default = 600),
-        "wheel_env": attr.string_dict(),
+        "timeout": attr.int(
+            default = 600,
+            doc = "Timeout (in seconds) on the rule's execution duration.",
+        ),
     },
     implementation = _pip_repository_impl,
+    doc = """A rule for importing `requirements.txt` dependencies into Bazel.
+
+This rule imports a `requirements.txt` file and generates a new
+`requirements.bzl` file.  This is used via the `WORKSPACE` pattern:
+
+```python
+pip_repository(
+    name = "foo",
+    requirements = ":requirements.txt",
+)
+```
+
+You can then reference imported dependencies from your `BUILD` file with:
+
+```python
+load("@foo//:requirements.bzl", "requirement")
+py_library(
+    name = "bar",
+    ...
+    deps = [
+       "//my/other:dep",
+       requirement("requests"),
+       requirement("numpy"),
+    ],
+)
+```
+
+Or alternatively:
+```python
+load("@foo//:requirements.bzl", "all_requirements")
+py_binary(
+    name = "baz",
+    ...
+    deps = [
+       ":foo",
+    ] + all_requirements,
+)
+```
+""",
 )
 
 def pip_install(requirements, name = DEFAULT_REPOSITORY_NAME, **kwargs):
+    """Imports a `requirements.txt` file and generates a new `requirements.bzl` file.
+
+    This is used via the `WORKSPACE` pattern:
+
+    ```python
+    pip_install(
+        requirements = ":requirements.txt",
+    )
+    ```
+
+    You can then reference imported dependencies from your `BUILD` file with:
+
+    ```python
+    load("@pip//:requirements.bzl", "requirement")
+    py_library(
+        name = "bar",
+        ...
+        deps = [
+           "//my/other:dep",
+           requirement("requests"),
+           requirement("numpy"),
+        ],
+    )
+    ```
+
+    Args:
+      requirements: A 'requirements.txt' pip requirements file.
+      name: A unique name for the created external repository (default 'pip').
+      **kwargs: Keyword arguments passed directly to the `pip_repository` repository rule.
+    """
     pip_repository(
         name = name,
         requirements = requirements,

experimental/rules_python_external/repositories.bzl

@@ -45,15 +45,18 @@ py_library(
 all_requirements = [name for (name, _, _) in _RULE_DEPS]
 
 def requirement(pkg):
-    return "@pypi__"+ pkg + "//:lib"
+    return "@pypi__" + pkg + "//:lib"
 
 def rules_python_external_dependencies():
+    """
+    Fetch dependencies these rules depend on. Workspaces that use the rules_python_external should call this.
+    """
     for (name, url, sha256) in _RULE_DEPS:
         maybe(
             http_archive,
             name,
-            url=url,
-            sha256=sha256,
-            type="zip",
-            build_file_content=_GENERIC_WHEEL,
+            url = url,
+            sha256 = sha256,
+            type = "zip",
+            build_file_content = _GENERIC_WHEEL,
         )