From 21e4aae743688320202c0b18d81b3acd07ba6259 Mon Sep 17 00:00:00 2001
From: UebelAndre <github@uebelandre.com>
Date: Mon, 17 Nov 2025 12:16:17 -0800
Subject: [PATCH] Improve documentation

---
 pex/defs.bzl       | 11 +++++++----
 pex/extensions.bzl |  6 +++---
 2 files changed, 10 insertions(+), 7 deletions(-)

diff --git a/pex/defs.bzl b/pex/defs.bzl
index 92a1fa0..e71d668 100644
--- a/pex/defs.bzl
+++ b/pex/defs.bzl
@@ -1,13 +1,17 @@
-"""# Pex
+"""# rules_pex
 
 Bazel rules for the Python executable packaging tool [pex](https://docs.pex-tool.org/).
 
-### Setup
+## Setup
+
+Below is an example of how to quickly setup toolchains which power the Pex rules. For details
+on customizing toolchains, please see the [`pex`](#pex) module extension or
+[`py_pex_toolchain`](#py_pex_toolchain) rule.
 
 ```python
 bazel_dep(name = "rules_pex", version = "{version}")
 
-pex = use_extension("//pex:extensions.bzl", "pex")
+pex = use_extension("@rules_pex//pex:extensions.bzl", "pex")
 pex.toolchain(
     name = "pex_toolchains",
 )
@@ -19,7 +23,6 @@ use_repo(
 
 register_toolchains(
     "@pex_toolchains//:all",
-    dev_dependency = True,
 )
 ```
 """
diff --git a/pex/extensions.bzl b/pex/extensions.bzl
index 2e322d8..60cc4d2 100644
--- a/pex/extensions.bzl
+++ b/pex/extensions.bzl
@@ -294,7 +294,7 @@ An extension for defining a pex toolchain.
 An example of defining and using a pex toolchain:
 
 ```python
-pex = use_extension("//pex:extensions.bzl", "pex")
+pex = use_extension("@rules_pex//pex:extensions.bzl", "pex")
 pex.toolchain(
     name = "pex_toolchains",
     pex_version = "2.67.3",
@@ -350,11 +350,11 @@ This tag is used to add fallback binaries for Windows platforms when the actual
 pex tools don't support Windows. This prevents toolchain resolution failures in
 multi-platform repositories.
 
-Note: Full Windows support is tracked in https://github.com/UebelAndre/rules_pex/issues/1
+Note: Full Windows support is tracked in <https://github.com/UebelAndre/rules_pex/issues/1>
 
 Example:
 ```python
-pex = use_extension("//pex:extensions.bzl", "pex")
+pex = use_extension("@rules_pex//pex:extensions.bzl", "pex")
 pex.toolchain(
     name = "pex_toolchains",
     python_version = "3.11",