Added docstrings to the new pip_repository rule

WORKSPACE

@@ -64,11 +64,11 @@ pip_repository(
 
 # New stuff
 
-load("//rules:new_repository.bzl", "pip_repositories")
+load("//rules:new_repository.bzl", new_pip_repository = "pip_repository")
 
-pip_repositories(
+new_pip_repository(
     name = "pip",
-    requirements = "//thirdparty/pip:requirements-lock.json"
+    requirements = "//thirdparty/pip:requirements-lock.json",
 )
 
 load("@pip//:requirements.bzl", "pip_install")

rules/new_repository.bzl

@@ -1,4 +1,4 @@
-def _pip_repositories_impl(repo_ctx):
+def _pip_repository_impl(repo_ctx):
     result = repo_ctx.execute([
         repo_ctx.path(repo_ctx.attr._generate_pip_repositories),
         repo_ctx.path(repo_ctx.attr.requirements),
@@ -12,11 +12,42 @@ def _pip_repositories_impl(repo_ctx):
     repo_ctx.file("BUILD")
 
 
-pip_repositories = repository_rule(
-    implementation = _pip_repositories_impl,
+pip_repository = repository_rule(
+    implementation = _pip_repository_impl,
+    doc = """
+        Defines an external workspace containing `py_library` targets for every
+        requirement found in the given requirements lock file.
+        
+        Each requirement in the lock file will be available via a label with the 
+        following format:
+        
+        `@<repo_name>//<distro_name>`
+
+        where `<repo_name>` is the name of this repository and `<distro_name>` is the
+        canonical name of the Python distribution found in the lock file. The canonical
+        name is all lowercase, with hyphens replaced by underscores. For example,
+        `PyYAML` would become `@pip//pyyaml` and `pytest-mock` would become 
+        `@pytest_mock`.
+
+        This rule also generates a `requirements.bzl` file containing a `pip_install` 
+        macro that should be loaded and invoked in the WORKSPACE file. This declares all 
+        of the repository rules for the required Python distributions.
+    """,
     attrs = {
-        "requirements": attr.label(allow_single_file = True),
-        "rules_pip_repo_name": attr.string(default = "com_apt_itude_rules_pip"),
+        "requirements": attr.label(
+            allow_single_file = True,
+            doc = """
+                The label of a requirements lock file, generated by the `pip_lock` rule, 
+                defining the required Python distributions.
+            """,
+        ),
+        "rules_pip_repo_name": attr.string(
+            default = "com_apt_itude_rules_pip",
+            doc = """
+                The workspace name that was used for the `rules_pip` repository, if not
+                the default.
+            """,
+        ),
         "_generate_pip_repositories": attr.label(
             default = "//src/bin:generate_pip_repositories.py",
             executable = True,