Various typo/doc clarifications

Author: rickeylev

BZLMOD_SUPPORT.md

@@ -45,6 +45,10 @@ 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")`.
+
+Note that using this builtin Bazel toolchain is deprecated and unsupported.
+See the {obj}`runtime_env_toolchains` docs for a replacement that is marginally
+better supported.
 **IMPORTANT: this should only be done in a root module, and may interfere with
 the toolchains rules_python registers**.
 

docs/index.md

@@ -8,8 +8,8 @@ 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.
 
-When using bazel 6 (or earlier), the core rules are bundled into the Bazel binary, and the symbols
-in this repository are simple aliases. On bazel 7 and above `rules_python` uses
+When using Bazel 6 (or earlier), the core rules are bundled into the Bazel binary, and the symbols
+in this repository are simple aliases. On Bazel 7 and above `rules_python` uses
 a separate Starlark implementation,
 see {ref}`Migrating from the Bundled Rules` below.
 
@@ -32,11 +32,12 @@ releases. In that case, please raise a GH issue.
 
 :::{topic} Sphinxdocs
 
-`sphinxdocs` rules allow users to generate documentation from bazel or
-Python source code.
+`sphinxdocs` rules allow users to generate documentation using Sphinx powered by Bazel, with additional functionality for documenting
+Starlark and Bazel code.
 
-This is available as is and the semantic versioning used by `rules_python` does
-not apply.
+The functionality is exposed because other projects find it useful, but 
+it is available as is and **the semantic versioning and
+compatibility policy used by `rules_python` does not apply**. 
 
 :::