docs: document the is_python config settings (#2336)

This documents the `//python/config_settings:is_python_*` config
settings. It adds a disclaimer
that the available targets may vary depending on the root module
settings, and tells users
how to match versions when one isn't available.

Author: rickeylev

docs/api/rules_python/python/config_settings/index.md

@@ -33,6 +33,44 @@ one of the values that `rules_python` maintains.
 Parses the value of the `python_version` and transforms it into a `X.Y` value.
 :::
 
+:::{bzl:target} is_python_*
+config_settings to match Python versions
+
+The name pattern is `is_python_X.Y` (to match major.minor) and `is_python_X.Y.Z`
+(to match major.minor.patch).
+
+Note that the set of available targets depends on the configured
+`TOOL_VERSIONS`. Versions may not always be available if the root module has
+customized them, or as older Python versions are removed from rules_python's set
+of builtin, known versions.
+
+If you need to match a version that isn't present, then you have two options:
+1. Manually define a `config_setting` and have it match {obj}`--python_version`
+   or {ob}`python_version_major_minor`. This works best when you don't control the
+   root module, or don't want to rely on the MODULE.bazel configuration. Such
+   a config settings would look like:
+   ```
+   # Match any 3.5 version
+   config_setting(
+       name = "is_python_3.5",
+       flag_values = {
+           "@rules_python//python/config_settings:python_version_major_minor": "3.5",
+       }
+   )
+   # Match exactly 3.5.1
+   config_setting(
+       name = "is_python_3.5.1",
+       flag_values = {
+           "@rules_python//python/config_settings:python_version": "3.5.1",
+       }
+   )
+   ```
+
+2. Use {obj}`python.single_override` to re-introduce the desired version so
+   that the corresponding `//python/config_setting:is_python_XXX` target is
+   generated.
+:::
+
 ::::{bzl:flag} exec_tools_toolchain
 Determines if the {obj}`exec_tools_toolchain_type` toolchain is enabled.