docs: tell how to emulate dependency groups with pip-compile (#3089)

While pyproject.toml is supported by piptools, dependency groups aren't.
They can be
emulated by using multiple files. Explain how to do that in the docs and
link to
the upstream feature request
(https://github.com/jazzband/pip-tools/issues/2062)

Along the way, link to our own feature request for pylock.toml support
in pip.parse.

---------

Co-authored-by: Ignas Anikevicius <240938+aignas@users.noreply.github.com>

docs/pypi/lock.md

diff --git a/docs/pypi/lock.md b/docs/pypi/lock.md
index db557fe..b5d8ec2 100644
--- a/docs/pypi/lock.md
+++ b/docs/pypi/lock.md
@@ -5,6 +5,8 @@
 
 :::{note}
 Currently `rules_python` only supports `requirements.txt` format.
+
+#{gh-issue}`2787` tracks `pylock.toml` support.
 :::
 
 ## requirements.txt
@@ -37,11 +39,33 @@
 Once you generate this fully specified list of requirements, you can install the requirements ([bzlmod](./download)/[WORKSPACE](./download-workspace)).
 
 :::{warning}
-If you're specifying dependencies in `pyproject.toml`, make sure to include the `[build-system]` configuration, with pinned dependencies. `compile_pip_requirements` will use the build system specified to read your project's metadata, and you might see non-hermetic behavior if you don't pin the build system.
+If you're specifying dependencies in `pyproject.toml`, make sure to include the
+`[build-system]` configuration, with pinned dependencies.
+`compile_pip_requirements` will use the build system specified to read your
+project's metadata, and you might see non-hermetic behavior if you don't pin the
+build system.
 
-Not specifying `[build-system]` at all will result in using a default `[build-system]` configuration, which uses unpinned versions ([ref](https://peps.python.org/pep-0518/#build-system-table)).
+Not specifying `[build-system]` at all will result in using a default
+`[build-system]` configuration, which uses unpinned versions
+([ref](https://peps.python.org/pep-0518/#build-system-table)).
 :::
 
+
+#### pip compile Dependency groups
+
+pip-compile doesn't yet support pyproject.toml dependency groups. Follow
+[pip-tools #2062](https://github.com/jazzband/pip-tools/issues/2062)
+to see the status of their support.
+
+In the meantime, support can be emulated by passing multiple files to `srcs`:
+
+```starlark
+compile_pip_requirements(
+    srcs = ["pyproject.toml", "requirements-dev.in"]
+    ...
+)
+```
+
 ### uv pip compile (bzlmod only)
 
 We also have experimental setup for the `uv pip compile` way of generating lock files.

python/private/pypi/pip_compile.bzl

diff --git a/python/private/pypi/pip_compile.bzl b/python/private/pypi/pip_compile.bzl
index 2e3e530..2892300 100644
--- a/python/private/pypi/pip_compile.bzl
+++ b/python/private/pypi/pip_compile.bzl
@@ -40,7 +40,7 @@
         tags = None,
         constraints = [],
         **kwargs):
-    """Generates targets for managing pip dependencies with pip-compile.
+    """Generates targets for managing pip dependencies with pip-compile (piptools).
 
     By default this rules generates a filegroup named "[name]" which can be included in the data
     of some other compile_pip_requirements rule that references these requirements
@@ -65,7 +65,10 @@
             * a requirements text file, usually named `requirements.in`
             * A `.toml` file, where the `project.dependencies` list is used as per
               [PEP621](https://peps.python.org/pep-0621/).
-        extra_args: passed to pip-compile.
+        extra_args: passed to pip-compile (aka `piptools`). See the
+            [pip-compile docs](https://pip-tools.readthedocs.io/en/latest/cli/pip-compile)
+            for args and meaning (passing `-h` and/or `--version` can help
+            inform what args are available)
         extra_deps: extra dependencies passed to pip-compile.
         generate_hashes: whether to put hashes in the requirements_txt file.
         py_binary: the py_binary rule to be used.