Improve subrule documentation

[Ubehebe]

Page link:

https://bazel.build/rules/lib/builtins/Subrule

Problem description (include actual vs expected text, if applicable):

Bazel 8.0 flipped the --experimental_rule_extension_api flag to true. But this wasn't mentioned in the release notes, and the official documentation for subrules just points to the design doc.

I've found subrules to be a valuable way to structure my Starlark code, and I use dozens of them in my Bazel repo. I'd like subrules to be better supported/documented across the Bazel ecosystem. This includes documenting the subrule API, but also providing APIs for documenting subrules themselves. (Currently, starlark_doc_extract ignores subrules.)

Where do you see this issue? (include link to specific section of the page, if applicable)

No response

Any other information you'd like to share?

No response

[Ubehebe]

CC @comius who I think implemented subrules (thank you!).