chore: improve the docs

Author: aignas

examples/bzlmod/MODULE.bazel.lock

@@ -3,8 +3,7 @@
 @generated by rules_python pip_parse repository rule.
 """
 
-load("@rules_python//python:pip.bzl", "pip_utils")
-load("@rules_python//python/pip_install:pip_repository.bzl", "group_library", "whl_library")
+load("@rules_python//python:pip.bzl", "group_library", "pip_utils", "whl_library")
 
 all_requirements = [
     "@my_project_pip_deps_vendored_certifi//:pkg",

examples/pip_parse_vendored/requirements.bzl

@@ -39,7 +39,7 @@ def gazelle_python_manifest(
             manifest, meaning testing it is just as expensive as generating it,
             but modifying it is much less likely to result in a merge conflict.
         pip_repository_name: the name of the pip_install or pip_repository target.
-        pip_deps_repository_name: deprecated - the old pip_install target name.
+        pip_deps_repository_name: deprecated - the old {bzl:obj}`pip_parse` target name.
         manifest: the Gazelle manifest file.
             defaults to the same value as manifest.
         **kwargs: other bazel attributes passed to the generate and test targets

gazelle/manifest/defs.bzl

@@ -55,7 +55,7 @@ func main() {
 		&pipRepositoryName,
 		"pip-repository-name",
 		"",
-		"The name of the pip_install or pip_repository target.")
+		"The name of the pip_parse or pip.parse target.")
 	flag.StringVar(
 		&modulesMappingPath,
 		"modules-mapping",

gazelle/manifest/generate/generate.go

@@ -42,7 +42,6 @@ def rules_python_internal_setup():
         python_versions = sorted(TOOL_VERSIONS.keys()),
     )
 
-    # Because we don't use the pip_install rule, we have to call this to fetch its deps
     pypi_deps()
 
     bazel_skylib_workspace()

internal_setup.bzl

@@ -12,7 +12,13 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"pip module extension for use with bzlmod"
+"""
+This is the successor to {bzl:obj}`pip_parse` for including third party PyPI dependencies into your bazel module using `bzlmod`.
+
+:::{seealso}
+For user documentation see the [PyPI dependencies section](pypi-dependencies).
+:::
+"""
 
 load("//python/private/pypi:pip.bzl", _pip = "pip")
 

python/extensions/pip.bzl

@@ -764,8 +764,7 @@ the BUILD files for wheels.
             attrs = _pip_parse_ext_attrs(),
             doc = """\
 This tag class is used to create a pip hub and all of the spokes that are part of that hub.
-This tag class reuses most of the pip attributes that are found in
-@rules_python//python/pip_install:pip_repository.bzl.
+This tag class reuses most of the attributes found in {bzl:obj}`pip_parse`.
 The exception is it does not use the arg 'repo_prefix'.  We set the repository
 prefix for the user and the alias arg is always True in bzlmod.
 """,
@@ -814,8 +813,7 @@ the BUILD files for wheels.
             ),
             doc = """\
 This tag class is used to create a pypi hub and all of the spokes that are part of that hub.
-This tag class reuses most of the pypi attributes that are found in
-@rules_python//python/pip_install:pip_repository.bzl.
+This tag class reuses most of the attributes found in {bzl:obj}`pip_parse`.
 The exception is it does not use the arg 'repo_prefix'.  We set the repository
 prefix for the user and the alias arg is always True in bzlmod.
 """,