docs: rules_python bzlmod GA and 1.0 prep

This is documenting the current state and closing the last remaining
TODO items for 1.0 release.

Work towards bazel-contrib#1361.

Author: aignas

BZLMOD_SUPPORT.md

@@ -2,10 +2,12 @@
 
 ## `rules_python` `bzlmod` support
 
-- Status: Beta
+- Status: GA
 - Full Feature Parity: No
+    - `rules_python`: Yes
+    - `rules_python_gazelle_plugin`: No (see below).
 
-Some features are missing or broken, and the public APIs are not yet stable.
+In general `bzlmod` has more features than `WORKSPACE` and users are encouraged to migrate.
 
 ## Configuration
 
@@ -27,15 +29,6 @@ A user does not use `local_path_override` stanza and would define the version in
 
 A second example, in [examples/bzlmod_build_file_generation](examples/bzlmod_build_file_generation) demonstrates the use of `bzlmod` to configure `gazelle` support for `rules_python`.
 
-## Feature parity
-
-This rule set does not have full feature partity with the older `WORKSPACE` type configuration:
-
-1. Gazelle does not support finding deps in sub-modules.  For instance we can have a dep like ` "@our_other_module//other_module/pkg:lib",` in a `py_test` definition.
-2. We have some features that are still not fully flushed out, and the user interface may change.
-
-Check ["issues"](/bazelbuild/rules_python/issues) for an up to date list.
-
 ## Differences in behavior from WORKSPACE
 
 ### Default toolchain is not the local system Python
@@ -52,10 +45,30 @@ platforms.
 If you want to use the same toolchain as what WORKSPACE used, then manually
 register the builtin Bazel Python toolchain by doing
 `register_toolchains("@bazel_tools//tools/python:autodetecting_toolchain")`.
-**IMPORTANT: this should only be done in a root module, and may intefere with
+**IMPORTANT: this should only be done in a root module, and may interfere with
 the toolchains rules_python registers**.
 
 NOTE: Regardless of your toolchain, due to
 [#691](https://github.com/bazelbuild/rules_python/issues/691), `rules_python`
 still relies on a local Python being available to bootstrap the program before
-handing over execution to the toolchain Python.
+handing over execution to the toolchain Python. To override this behaviour see
+{obj}`--bootstrap_impl=script`, which switches to `bash`-based bootstrap on
+UNIX systems.
+
+### Better PyPI package downloading on bzlmod
+
+On `bzlmod` users have the option to use the `bazel_downloader` to download packages
+and work correctly when `host` platform is not the same as the `target` platform. This
+provides faster package download times and integration with the credentials helper.
+
+### Extra targets in `whl_library` repos
+
+Due to how `bzlmod` is designed and the visibility rules that it enforces, it is best to use
+the targets in the `whl` repos as they are and not rely on using the `annotations` API to
+add extra targets to so-called `spoke` repos. For alternatives that should cover most of the
+existing usecases please see:
+* {bzl:obj}`py_console_script_binary` to create `entry_point` targets.
+* {bzl:obj}`whl_filegroup` to extract filegroups from the `whl` targets (e.g. `@pip//numpy:whl`)
+* {bzl:obj}`pip.override` to patch the downloaded `whl` files. Using that you
+  can change the `METADATA` of the `whl` file that will influence how
+  `rules_python` code generation behaves.

docs/index.md

@@ -1,32 +1,54 @@
 # Python Rules for Bazel
 
-rules_python is the home of the core Python rules -- `py_library`,
-`py_binary`, `py_test`, `py_proto_library`, and related symbols that provide the basis for Python
-support in Bazel. It also contains package installation rules for integrating with PyPI and other indices.
+`rules_python` is the home for 4 major components:
+* the core Python rules -- `py_library`, `py_binary`, `py_test`,
+  `py_proto_library`, and related symbols that provide the basis for Python
+  support in Bazel.
+
+  This is subject to our breaking change policy outlined in the <support>.
+* Package installation rules for integrating with PyPI and other SimpleAPI
+  complying indexes.
+
+  This is still `experimental` and the APIs might change more often than the
+  core rules or you may experience regressions between the minor releases. In
+  that case, please raise tickets to the GH issues bug tracker.
+* `sphinxdocs` rules allowing users to generate documentation from bazel or
+  Python source code.
+
+  This is available as is and without any guarantees. The semantic versioning
+  used by `rules_python` does not apply to bazel rules or the output.
+* `gazelle` plugin for generating `BUILD.bazel` files based on Python source
+  code.
+
+  This is available as is and without any guarantees. The semantic versioning
+  used by `rules_python` does not apply to the plugin.
 
 Documentation for rules_python lives here and in the
 [Bazel Build Encyclopedia](https://docs.bazel.build/versions/master/be/python.html).
 
 Examples are in the {gh-path}`examples` directory.
 
-Currently, the core rules build into the Bazel binary, and the symbols in this
-repository are simple aliases. However, we are migrating the rules to Starlark and removing them from the Bazel binary. Therefore, the future-proof way to depend on Python rules is via this repository. See
-{ref}`Migrating from the Bundled Rules` below.
+When using bazel 6, the core rules built into the Bazel binary, and the symbols
+in this repository are simple aliases. However, on bazel 7 and above starlark
+implementation in this repository is used.
+See {ref}`Migrating from the Bundled Rules` below.
 
 The core rules are stable. Their implementation in Bazel is subject to Bazel's
 [backward compatibility policy](https://docs.bazel.build/versions/master/backward-compatibility.html).
 Once migrated to rules_python, they may evolve at a different
 rate, but this repository will still follow [semantic versioning](https://semver.org).
 
-The Bazel community maintains this repository. Neither Google nor the Bazel team provides support for the code. However, this repository is part of the test suite used to vet new Bazel releases. See
-{gh-path}`How to contribute <CONTRIBUTING.md>` for information on our development workflow.
+The Bazel community maintains this repository. Neither Google nor the Bazel
+team provides support for the code. However, this repository is part of the
+test suite used to vet new Bazel releases. See {gh-path}`How to contribute
+<CONTRIBUTING.md>` for information on our development workflow.
 
 ## Bzlmod support
 
-- Status: Beta
-- Full Feature Parity: No
+- Status: GA
 
-See {gh-path}`Bzlmod support <BZLMOD_SUPPORT.md>` for more details
+See {gh-path}`Bzlmod support <BZLMOD_SUPPORT.md>` for any behaviour differences between
+`bzlmod` and `WORKSPACE`.
 
 ## Migrating from the bundled rules