docs: describe `annotations` attr of `pip_parse` (#1667)
My default expectation would be that the keys to the `annotations`
dictionary passed to `pip_parse` would use the `normalize_name(...)`
convention, as is used elsewhere in the API. However, this does not
appear to be the case. I originally was going to file a bug, but maybe
just documenting the current behavior is enough?
For a minimal repro showing that this capitalization is indeed required,
see https://github.com/bruno-digitbio/bug-rules-python-annotation-pyqt
In that repo,
```bash
$ bazel run //:test_has_comment
$ tail $(bazel info output_base)/external/pip_pyqt6/BUILD.bazel
$ tail $(bazel info output_base)/external/pip_wheel/BUILD.bazel
```
will both show `# A comment` at the bottom, as requested in the
`WORKSPACE` file. However, if you first run
```bash
$ bazel run //:requirements.update
```
then the auto-generated requirements file will use lowercase for the
requirement specification, breaking the desired behavior.
Please let me know if it makes more sense to just check in the docs,
include this example (or something similar) as a small test, or
something else. Apologies if I missed anything in the contribution
guidelines!
diff --git a/python/private/pypi/pip_repository.bzl b/python/private/pypi/pip_repository.bzl
index 992b83f..137c524 100644
--- a/python/private/pypi/pip_repository.bzl
+++ b/python/private/pypi/pip_repository.bzl
@@ -214,7 +214,12 @@
pip_repository = repository_rule(
attrs = dict(
annotations = attr.string_dict(
- doc = "Optional annotations to apply to packages",
+ doc = """\
+Optional annotations to apply to packages. Keys should be package names, with
+capitalization matching the input requirements file, and values should be
+generated using the `package_name` macro. For example usage, see [this WORKSPACE
+file](https://github.com/bazelbuild/rules_python/blob/main/examples/pip_repository_annotations/WORKSPACE).
+""",
),
_template = attr.label(
default = ":requirements.bzl.tmpl.workspace",
