Exposed docs for compile_pip_requirements (#534)

Co-authored-by: Alex Eagle <[email protected]>

Author: UebelAndre

docs/BUILD

@@ -59,6 +59,10 @@ bzl_library(
     srcs = [
         "//python/pip_install:pip_repository.bzl",
         "//python/pip_install:repositories.bzl",
+        "//python/pip_install:requirements.bzl",
+    ],
+    deps = [
+        ":defs",
     ],
 )
 

docs/pip.md

@@ -1,5 +1,40 @@
 <!-- Generated with Stardoc: http://skydoc.bazel.build -->
 
+<a name="#compile_pip_requirements"></a>
+
+## compile_pip_requirements
+
+<pre>
+compile_pip_requirements(<a href="#compile_pip_requirements-name">name</a>, <a href="#compile_pip_requirements-extra_args">extra_args</a>, <a href="#compile_pip_requirements-visibility">visibility</a>, <a href="#compile_pip_requirements-requirements_in">requirements_in</a>, <a href="#compile_pip_requirements-requirements_txt">requirements_txt</a>, <a href="#compile_pip_requirements-tags">tags</a>,
+                         <a href="#compile_pip_requirements-kwargs">kwargs</a>)
+</pre>
+
+    Macro creating targets for running pip-compile
+
+Produce a filegroup by default, named "[name]" which can be included in the data
+of some other compile_pip_requirements rule that references these requirements
+(e.g. with `-r ../other/requirements.txt`)
+
+Produce two targets for checking pip-compile:
+
+- validate with `bazel test <name>_test`
+- update with   `bazel run <name>.update`
+
+
+**PARAMETERS**
+
+
+| Name  | Description | Default Value |
+| :-------------: | :-------------: | :-------------: |
+| name |  base name for generated targets, typically "requirements"   |  none |
+| extra_args |  passed to pip-compile   |  <code>[]</code> |
+| visibility |  passed to both the _test and .update rules   |  <code>["//visibility:private"]</code> |
+| requirements_in |  file expressing desired dependencies   |  <code>None</code> |
+| requirements_txt |  result of "compiling" the requirements.in file   |  <code>None</code> |
+| tags |  tagging attribute common to all build rules, passed to both the _test and .update rules   |  <code>None</code> |
+| kwargs |  other bazel attributes passed to the "_test" rule   |  none |
+
+
 <a name="#pip_import"></a>
 
 ## pip_import

examples/pip_install/BUILD

@@ -6,7 +6,7 @@ load(
     "requirement",
 )
 load("@rules_python//python:defs.bzl", "py_binary", "py_test")
-load("@rules_python//python/pip_install:requirements.bzl", "compile_pip_requirements")
+load("@rules_python//python:pip.bzl", "compile_pip_requirements")
 
 # Toolchain setup, this is optional.
 # Demonstrate that we can use the same python interpreter for the toolchain and executing pip in pip install (see WORKSPACE).

examples/pip_parse/BUILD

@@ -1,6 +1,6 @@
 load("@pip_parsed_deps//:requirements.bzl", "entry_point", "requirement")
 load("@rules_python//python:defs.bzl", "py_binary", "py_test")
-load("@rules_python//python/pip_install:requirements.bzl", "compile_pip_requirements")
+load("@rules_python//python:pip.bzl", "compile_pip_requirements")
 
 # Toolchain setup, this is optional.
 # Demonstrate that we can use the same python interpreter for the toolchain and executing pip in pip install (see WORKSPACE).

python/pip.bzl

@@ -15,6 +15,9 @@
 
 load("//python/pip_install:pip_repository.bzl", "pip_repository")
 load("//python/pip_install:repositories.bzl", "pip_install_dependencies")
+load("//python/pip_install:requirements.bzl", _compile_pip_requirements = "compile_pip_requirements")
+
+compile_pip_requirements = _compile_pip_requirements
 
 def pip_install(requirements, name = "pip", **kwargs):
     """Imports a `requirements.txt` file and generates a new `requirements.bzl` file.

python/pip_install/BUILD

@@ -13,17 +13,11 @@ filegroup(
 
 filegroup(
     name = "bzl",
-    srcs = [
-        "pip_repository.bzl",
-        "repositories.bzl",
-    ],
+    srcs = glob(["*.bzl"]),
     visibility = ["//:__pkg__"],
 )
 
 exports_files(
-    [
-        "pip_repository.bzl",
-        "repositories.bzl",
-    ],
+    glob(["*.bzl"]),
     visibility = ["//docs:__pkg__"],
 )

python/pip_install/requirements.bzl

@@ -1,4 +1,4 @@
-"Rules to verify and update pip-compile locked requirements.txt"
+"""Rules to verify and update pip-compile locked requirements.txt"""
 
 load("//python:defs.bzl", "py_binary", "py_test")
 load("//python/pip_install:repositories.bzl", "requirement")