add docs

Author: aignas

python/uv/private/lock.bzl

@@ -21,7 +21,6 @@ Differences with the current {obj}`compile_pip_requirements` rule:
 - This does not error out if the output file does not exist yet.
 - Supports transitions out of the box.
 
-
 Note, this does not provide a `test` target, if you would like to add a test
 target that always does the locking automatically to ensure that the
 `requirements.txt` file is up-to-date, add something similar to:
@@ -283,6 +282,17 @@ def _maybe_file(path):
 def lock(*, name, srcs, out, args = [], env = None, **kwargs):
     """Pin the requirements based on the src files.
 
+    This macro creates the following targets:
+    - `name`: the target that creates the requirements.txt file in a build
+      action.
+    - `name.run`: a runnable target that can be used to pass extra parameters
+      to the same command that would be run in the `name` action. This will
+      update the source copy of the requirements file.
+    - `name.update`: a target that can be run to update the source-tree version
+      of the requirements lock file. The output can be fed to the
+      {obj}`pip.parse` bzlmod extension tag class. Note, you can use
+      `native_test` to wrap this target to make a test.
+
     Args:
         name: The name of the target to run for updating the requirements.
         srcs: The srcs to use as inputs.
@@ -295,8 +305,11 @@ def lock(*, name, srcs, out, args = [], env = None, **kwargs):
     """
     update_target = "{}.update".format(name)
     locker_target = "{}.run".format(name)
+
+    # Check if the output file already exists, if yes, first copy it to the
+    # output file location in order to make `uv` not change the requirements if
+    # we are just running the command.
     maybe_out = _maybe_file(out)
-    out_new = name + ".out"
     target_compatible_with = kwargs.pop("target_compatible_with", None)
     if target_compatible_with == None and not BZLMOD_ENABLED:
         target_compatible_with = ["@platforms//:incompatible"]
@@ -310,9 +323,6 @@ def lock(*, name, srcs, out, args = [], env = None, **kwargs):
     _lock(
         name = name,
         srcs = srcs,
-        # Check if the output file already exists, if yes, first copy it to the
-        # output file location in order to make `uv` not change the requirements if
-        # we are just running the command.
         existing_output = maybe_out,
         update_target = update_target,
         tags = [
@@ -346,7 +356,7 @@ def lock(*, name, srcs, out, args = [], env = None, **kwargs):
         template = "//python/uv/private:lock_copier.py",
         substitutions = {
             "{{dst}}": "{}/{}".format(pkg, out),
-            "{{src}}": "{}/{}".format(pkg, out_new),
+            "{{src}}": "{}/{}.out".format(pkg, name),
             "{{update_target}}": "//{}/{}".format(pkg, update_target),
         },
     )