Enhance documentation on toolchains

[bertulli]

I was trying out Bazel for rust development, and I noticed the current global migration from WORKSPACE files to MODULE.bazel ones. On the rules_rust's homepage, under bzlmod, is listed how to download and use the Rust rules, but then the instructions on how to use a specific toolchain are valid, IIUC, only for WORKSPACE files:

## For old WORKSPACE files
rust_register_toolchains(
    edition = "2021",
    versions = [
        "1.79.0"
    ],
)

The indentation level of that part suggests it is also valid for MODULE.bazel files, but on my machine it isn't, and looking at the examples provided by Bazel, this should be changed in something similar to

# Rust toolchain
RUST_EDITION = "2021"

RUST_VERSION = "1.79.0"

rust = use_extension("@rules_rust//rust:extensions.bzl", "rust")
rust.toolchain(
    edition = RUST_EDITION,
    versions = [RUST_VERSION],
)
use_repo(rust, "rust_toolchains")

register_toolchains("@rust_toolchains//:all")

If my understanding is right, I think it would be beneficial to update the docs, if you want I can open a PR for it 👍 Thanks!

[mikn]

Yes, the module extension interface for managing rust toolchains is largely undocumented currently making it very confusing to try to use rules_rust with Bzlmod.

[UebelAndre]

I just did some refactors to the documentation here (#3114) which basically deletes complexity in how rules_rust used to manage documentation. I'd be happy to review a PR to improve bzlmod doc and hope the recent changes make that easier to integrate!