From bff5ce13f46d1cf7b21307f9af2a89d19436e057 Mon Sep 17 00:00:00 2001
From: Ignas Anikevicius <240938+aignas@users.noreply.github.com>
Date: Sun, 7 Dec 2025 23:32:22 +0900
Subject: [PATCH 1/3] document the target_platforms attribute

---
 docs/pypi/download.md | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/docs/pypi/download.md b/docs/pypi/download.md
index c40f2d4347..cba9f03d6a 100644
--- a/docs/pypi/download.md
+++ b/docs/pypi/download.md
@@ -113,6 +113,21 @@ This will not work for sdists with C extensions, but pure Python sdists may stil
 approach.
 :::
 
+By default we select the host `{os}_{arch}` platform defined in the `rules_python` `MODULE.bazel`
+file. This means that `rules_python` by default does not come with cross-platform building support
+because some packages have very large wheels and users should be able to use `bazel query` with
+minimal overhead. As a result, we think that it is up to the user to configure the `pip.parse`
+calls and select which platforms they want to target via
+{obj}`pip.parse.target_platforms` attribute:
+```starlark
+    # Enable free threaded and non-freethreaded switching on the host platform
+    target_platforms = ["{os}_{arch}", "{os}_{arch}_freethreaded"],
+
+    # Enable building for `linux_x86_64` containers and the host platform.
+    target_platforms = ["{os}_{arch}", "linux_x86_64"],
+)
+```
+
 ### Using `download_only` attribute
 
 Let's say you have two requirements files:

From 57bc3f8fc6adc857ba1cd255f23455618ddcb614 Mon Sep 17 00:00:00 2001
From: Ignas Anikevicius <240938+aignas@users.noreply.github.com>
Date: Mon, 8 Dec 2025 00:29:33 +0900
Subject: [PATCH 2/3] Update docs/pypi/download.md

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
---
 docs/pypi/download.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/docs/pypi/download.md b/docs/pypi/download.md
index cba9f03d6a..ebc3eb8fea 100644
--- a/docs/pypi/download.md
+++ b/docs/pypi/download.md
@@ -113,12 +113,12 @@ This will not work for sdists with C extensions, but pure Python sdists may stil
 approach.
 :::
 
-By default we select the host `{os}_{arch}` platform defined in the `rules_python` `MODULE.bazel`
-file. This means that `rules_python` by default does not come with cross-platform building support
+By default, `rules_python` selects the host `{os}_{arch}` platform from its `MODULE.bazel`
+file. This means that `rules_python` by default does not provide cross-platform building support
 because some packages have very large wheels and users should be able to use `bazel query` with
-minimal overhead. As a result, we think that it is up to the user to configure the `pip.parse`
-calls and select which platforms they want to target via
-{obj}`pip.parse.target_platforms` attribute:
+minimal overhead. As a result, users should configure their `pip.parse`
+calls and select which platforms they want to target via the
+{attr}`pip.parse.target_platforms` attribute:
 ```starlark
     # Enable free threaded and non-freethreaded switching on the host platform
     target_platforms = ["{os}_{arch}", "{os}_{arch}_freethreaded"],

From 395aa13b559a0ef19d26e291988d02de1282c44b Mon Sep 17 00:00:00 2001
From: Ignas Anikevicius <240938+aignas@users.noreply.github.com>
Date: Mon, 8 Dec 2025 00:29:42 +0900
Subject: [PATCH 3/3] Update docs/pypi/download.md

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
---
 docs/pypi/download.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/pypi/download.md b/docs/pypi/download.md
index ebc3eb8fea..258f211301 100644
--- a/docs/pypi/download.md
+++ b/docs/pypi/download.md
@@ -120,11 +120,11 @@ minimal overhead. As a result, users should configure their `pip.parse`
 calls and select which platforms they want to target via the
 {attr}`pip.parse.target_platforms` attribute:
 ```starlark
-    # Enable free threaded and non-freethreaded switching on the host platform
+    # Example of enabling free threaded and non-freethreaded switching on the host platform:
     target_platforms = ["{os}_{arch}", "{os}_{arch}_freethreaded"],
 
-    # Enable building for `linux_x86_64` containers and the host platform.
-    target_platforms = ["{os}_{arch}", "linux_x86_64"],
+    # As another example, to enable building for `linux_x86_64` containers and the host platform:
+    # target_platforms = ["{os}_{arch}", "linux_x86_64"],
 )
 ```