docs: explain --workspace_status_command usage with example

[abishekgiri]

What does this PR do?

This PR adds a new Usage subsection under --workspace_status_command in the user manual.

The existing documentation explains how to provide a workspace status script, but does not show how build rules can actually consume the generated values. This change fills that gap.

---

What’s included?

• A clear explanation of how Bazel writes status values to:
  • bazel-out/stable-status.txt
  • bazel-out/volatile-status.txt
• A portable Python-based status script example
• A genrule example showing how stamped rules can read values from stable-status.txt
• Notes on stable vs volatile keys and their impact on caching

---

Why is this useful?

Users frequently ask how to use values produced by --workspace_status_command inside rules (e.g. for embedding build metadata). This documentation provides a minimal, concrete example without requiring custom Starlark rules.

---

Verification

I verified the examples locally by:

1. Creating a Python workspace status script
2. Running a stamped genrule that reads from stable-status.txt
3. Confirming the expected key appears in the generated output

---

Fixes #21200

[gemini-code-assist]

Code Review

This pull request adds a much-needed "Usage" section to the --workspace_status_command documentation, explaining how to consume the generated status files with a clear example. This is a great improvement.

However, the genrule example uses a hardcoded path bazel-out/stable-status.txt which is not robust and may fail in sandboxed environments. I've left a suggestion to use the $(BINDIR) "Make" variable for a more reliable path to the status file.

[gemini-code-assist]

The path bazel-out/stable-status.txt is not guaranteed to be valid within the genrule execution environment. This path is a symlink in the workspace root, but the genrule command runs in the execution root, where such a symlink may not exist, especially with sandboxing.

A more robust way to refer to the stable-status.txt file is by using the $(BINDIR) "Make" variable, which expands to the configuration-specific bin directory where the status files are generated.

Suggested change

	cmd = "grep STABLE_PYTHON_VERSION bazel-out/stable-status.txt > $@",
	cmd = "grep STABLE_PYTHON_VERSION \$(BINDIR)/stable-status.txt > $@",