docs: various howto guides (#3157)

Create a "How to" section of docs that explain how to accomplish
specific tasks.

While these things can be inferred from the various API references,
those are large
and overwhelming, which can make it hard to figure it out. Instead,
provide how to
guides from tasks that we've seen users ask about.

Fixes #3044

Author: rickeylev

docs/howto/build-a-wheel.md

@@ -0,0 +1,87 @@
+:::{default-domain} bzl
+:::
+
+# How to build a wheel
+
+This guide explains how to use the `py_wheel` rule to build a wheel
+file from a `py_library`.
+
+## Basic usage
+
+The `py_wheel` rule takes any file-providing target as input and put its files
+into a wheel. Because `py_library` provides its source files, simple cases can
+pass `py_library` directly to `py_wheel`:
+
+```starlark
+# BUILD.bazel
+
+py_library(
+    name = "my_project_lib",
+    srcs = glob(["my_project/**/*.py"]),
+    # ...
+)
+
+py_wheel(
+    name = "my_project_wheel",
+    distribution = "my-project",
+    version = "0.1.0",
+    deps = [":my_project_lib"],
+)
+```
+
+The above will include the *default outputs* of the `py_library`, which are the
+direct `.py` files listed in the py library. It does **not** include transitive
+dependencies.
+
+## Including and filtering transitive dependencies
+
+
+Use the `py_package` rule to include and filter the transitive parts of
+a `py_library` target.
+
+The `py_package` rule has a `packages` attribute that takes a list of dotted
+Python package names to include. All files and dependencies of those packages
+are included.
+
+Here is an example:
+
+```starlark
+# BUILD.bazel
+
+py_library(
+    name = "my_project_lib",
+    srcs = glob(["my_project/**/*.py"]),
+    deps = ["@pypi//some_dep"],
+)
+
+py_package(
+    name = "my_project_package",
+    # This will only include files for the "my_package" package; other files
+    # will be excluded.
+    packages = ["my_project"],
+)
+
+py_wheel(
+    name = "my_project_wheel",
+    distribution = "my-project",
+    version = "0.1.0",
+    # The `py_wheel` rule takes the `py_package` target in the `deps`
+    # attribute.
+    deps = [":my_project_package"],
+)
+```
+
+## Disabling `__init__.py` generation
+
+By default, Bazel automatically creates `__init__.py` files in directories to
+make them importable. This can sometimes be undesirable when building wheels
+because it interfers with namespace packages or makes directories importable
+that shouldn't be importable.
+
+It's highly recommended to disable this behavior by setting a flag in your
+`.bazelrc` file:
+
+```
+# .bazelrc
+build --incompatible_default_to_explicit_init_py=true
+```

docs/howto/get-python-version.md

@@ -0,0 +1,57 @@
+:::{default-domain} bzl
+:::
+
+# How to get the current Python version
+
+This guide explains how to use a [toolchain](toolchains) to get the current Python
+version and, as an example, write it to a file.
+
+You can create a simple rule that accesses the Python toolchain and retrieves
+the version string.
+
+## The rule implementation
+
+Create a file named `my_rule.bzl`:
+
+```starlark
+# my_rule.bzl
+def _my_rule_impl(ctx):
+    toolchain = ctx.toolchains["@rules_python//python:toolchain_type"]
+    info = toolchain.py3_runtime.interpreter_version_info
+    python_version = str(info.major) + "." + str(info.minor) + "." + str(info.micro)
+
+    output_file = ctx.actions.declare_file(ctx.attr.name + ".txt")
+    ctx.actions.write(
+        output = output_file,
+        content = python_version,
+    )
+
+    return [DefaultInfo(files = depset([output_file]))]
+
+my_rule = rule(
+    implementation = _my_rule_impl,
+    attrs = {},
+    toolchains = ["@rules_python//python:toolchain_type"],
+)
+```
+
+## Using the rule
+
+In your `BUILD.bazel` file, you can use the rule like this:
+
+```starlark
+# BUILD.bazel
+load(":my_rule.bzl", "my_rule")
+
+my_rule(
+    name = "show_python_version",
+)
+```
+
+When you build this target, it will generate a file named
+`show_python_version.txt` containing the Python version (e.g., `3.9`).
+
+```starlark
+bazel build :show_python_version
+cat bazel-bin/show_python_version.txt
+```

docs/howto/index.md

@@ -0,0 +1,13 @@
+:::{default-domain} bzl
+:::
+
+# How-to Guides
+
+This section contains a collection of how-to guides for accomplishing specific tasks with `rules_python`.
+
+```{toctree}
+:maxdepth: 1
+:glob:
+
+*
+```

docs/howto/linking-libpython.md

@@ -0,0 +1,66 @@
+:::{default-domain} bzl
+:::
+
+# How to link to libpython
+
+This guide explains how to use the Python [toolchain](toolchains) to get the linker
+flags required for linking against `libpython`. This is often necessary when
+embedding Python in a C/C++ application.
+
+Currently, the `:current_py_cc_libs` target does *not* include `-lpython` et al
+linker flags. This is intentional because it forces dynamic linking (via the
+dynamic linker processing `DT_NEEDED` entries), which prevents users who want
+to load it in some more custom way.
+
+## Exposing linker flags in a rule
+
+You can create a rule that gets the Python version from the toolchain and
+constructs the correct linker flag. This rule can then provide the flag to
+other C/C++ rules via the `CcInfo` provider.
+
+Here's an example of a rule that creates the `-lpython<version>` flag:
+
+```starlark
+# python_libs.bzl
+load("@bazel_tools//tools/cpp:toolchain_utils.bzl", "cc_common")
+
+def _python_libs_impl(ctx):
+    toolchain = ctx.toolchains["@rules_python//python:toolchain_type"]
+    info = toolchain.py3_runtime.interpreter_version_info
+    link_flag = "-lpython{}.{}".format(info.major, info.minor)
+
+    cc_info = CcInfo(
+        linking_context = cc_common.create_linking_context(
+            user_link_flags = [link_flag],
+        ),
+    )
+    return [cc_info]
+
+python_libs = rule(
+    implementation = _python_libs_impl,
+    toolchains = ["@rules_python//python:toolchain_type"],
+)
+```
+
+## Using the rule
+
+In your `BUILD.bazel` file, define a target using this rule and add it to the
+`deps` of your `cc_binary` or `cc_library`.
+
+```starlark
+# BUILD.bazel
+load(":python_libs.bzl", "python_libs")
+
+python_libs(
+    name = "py_libs",
+)
+
+cc_binary(
+    name = "my_app",
+    srcs = ["my_app.c"],
+    deps = [
+        ":py_libs",
+        # Other dependencies
+    ],
+)
+```

docs/howto/pypi-headers.md

@@ -0,0 +1,109 @@
+:::{default-domain} bzl
+:::
+
+# How to expose headers from a PyPI package
+
+When you depend on a PyPI package that includes C headers (like `numpy`), you
+need to make those headers available to your `cc_library` or
+`cc_binary` targets.
+
+The recommended way to do this is to inject a `BUILD.bazel` file into the
+external repository for the package. This `BUILD` file will create
+a `cc_library` target that exposes the header files.
+
+First, create a `.bzl` file that has the extra logic we'll inject. Putting it
+in a separate bzl file avoids having to redownload and extract the whl file
+when our logic changes.
+
+```bzl
+
+# pypi_extra_targets.bzl
+load("@rules_cc//cc:cc_library.bzl", "cc_library")
+
+def extra_numpy_targets():
+    cc_library(
+        name = "headers",
+        hdrs = glob(["**/*.h"]),
+        visibility = ["//visibility:public"],
+    )
+```
+
+## Bzlmod setup
+
+In your `MODULE.bazel` file, use the `build_file_content` attribute of
+`pip.parse` to inject the `BUILD` file content for the `numpy` package.
+
+```bazel
+# MODULE.bazel
+load("@rules_python//python/extensions:pip.bzl", "parse", "whl_mods")
+pip = use_extension("@rules_python//python/extensions:pip.bzl", "pip")
+whl_mods = use_extension("@rules_python//python/extensions:pip.bzl", "whl_mods")
+
+
+# Define a specific modification for a wheel
+whl_mods(
+    hub_name = "pypi_mods",
+    whl_name = "numpy-1.0.0-py3-none-any.whl", # The exact wheel filename
+    additive_build_content = """
+load("@//:pypi_extra_targets.bzl", "numpy_hdrs")
+
+extra_numpy_targets()
+""",
+)
+pip.parse(
+    hub_name = "pypi",
+    wheel_name = "numpy",
+    requirements_lock = "//:requirements.txt",
+    whl_modifications = {
+        "@pypi_mods//:numpy.json": "numpy",
+    },
+    extra_hub_aliases = {
+        "numpy": ["headers"],
+    }
+)
+```
+
+## WORKSPACE setup
+
+In your `WORKSPACE` file, use the `annotations` attribute of `pip_parse` to
+inject additional `BUILD` file content, then use `extra_hub_targets` to expose
+that target in the `@pypi` hub repo.
+
+The {obj}`package_annotation` helper can be used to construct the value for the
+`annotations` attribute.
+
+```starlark
+# WORKSPACE
+load("@rules_python//python:pip.bzl", "package_annotation", "pip_parse")
+
+pip_parse(
+    name = "pypi",
+    requirements_lock = "//:requirements.txt",
+    annotations = {
+        "numpy": package_annotation(
+            additive_build_content = """\
+load("@//:pypi_extra_targets.bzl", "numpy_hdrs")
+
+extra_numpy_targets()
+"""
+        ),
+    },
+    extra_hub_targets = {
+        "numpy": ["headers"],
+    },
+)
+```
+
+## Using the headers
+
+In your `BUILD.bazel` file, you can now depend on the generated `headers`
+target.
+
+```bazel
+# BUILD.bazel
+cc_library(
+    name = "my_c_extension",
+    srcs = ["my_c_extension.c"],
+    deps = ["@pypi//numpy:headers"],
+)
+```

docs/howto/python-headers.md

@@ -0,0 +1,30 @@
+:::{default-domain} bzl
+:::
+
+# How to get Python headers for C extensions
+
+When building a Python C extension, you need access to the Python header
+files. This guide shows how to get the necessary include paths from the Python
+[toolchain](toolchains).
+
+The recommended way to get the headers is to depend on the
+`@rules_python//python/cc:current_py_cc_headers` target. This is a helper
+target that uses toolchain resolution to find the correct headers for the
+target platform.
+
+## Using the headers
+
+In your `BUILD.bazel` file, you can add `@rules_python//python/cc:current_py_cc_headers`
+to the `deps` of a `cc_library` or `cc_binary` target.
+
+```bazel
+# BUILD.bazel
+cc_library(
+    name = "my_c_extension",
+    srcs = ["my_c_extension.c"],
+    deps = ["@rules_python//python/cc:current_py_cc_headers"],
+)
+```
+
+This setup ensures that your C extension code can find and use the Python
+headers during compilation.

docs/index.md

@@ -102,6 +102,7 @@ precompiling
 gazelle/docs/index
 REPL <repl>
 Extending <extending>
+How-to Guides <howto/index>
 Contributing <contributing>
 devguide
 support