docs: describe `annotations` attr of `pip_parse`

[bruno-digitbio]

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,

$ 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

$ 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!

[google-cla[bot]]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[bruno-digitbio]

Having trouble signing the CLA, is this transient/typical or should I reach out to someone for help?

[rickeylev]

Perhaps try again today? I didn't see any server errors when I triggered it to re-run; just the usual "person hasn't signed CLA" error. There isn't a CLA record for bruno-digitbio, so try re-submitting your CLA form.

It looks like your profile is marked pretty private ? Perhaps this requirement is what's tripping it up:

You may have Keep my email address private enabled. Without a visible email address, the CLA cannot be checked. Uncheck it and re-create the offending commit, or have your CLA point of contact add your @users.noreply.github.com address to the CLA group.

[github-actions[bot]]

This Pull Request has been automatically marked as stale because it has not had any activity for 180 days. It will be closed if no further activity occurs in 30 days. Collaborators can add an assignee to keep this open indefinitely. Thanks for your contributions to rules_python!

[bruno-digitbio]

Perhaps try again today?

I tried every couple of weeks and eventually gave up, but today I logged in and it magically worked!

It looks like your profile is marked pretty private ? Perhaps this requirement is what's tripping it up:

You may have Keep my email address private enabled. Without a visible email address, the CLA cannot be checked. Uncheck it and re-create the offending commit, or have your CLA point of contact add your @users.noreply.github.com address to the CLA group.

I don't think it was this specific setting, but it was probably some other similar privacy setting that I've since relaxed!

Not sure how to un-mark this as stale but I rebased it and looks like the docs update would still be valuable, but let me know if I should change it at all!