docs(build_recipes): add initial build recipes structure

.pre-commit-config.yaml

@@ -34,7 +34,7 @@ repos:
         entry: poetry run cfn-lint
         language: system
         types: [yaml]
-        exclude: examples/homepage/install/.*?/serverless\.yml$
+        exclude: examples/build_recipes/*
         files: examples/.*
   - repo: https://github.com/rhysd/actionlint
     rev: "fd7ba3c382e13dcc0248e425b4cbc3f1185fa3ee" # v1.6.24

docs/build_recipes/getting-started.md

@@ -0,0 +1,30 @@
+---
+title: Getting Started
+description: Prerequisites and setup for building Lambda functions with Powertools
+---
+
+<!-- markdownlint-disable MD043 -->
+
+## Prerequisites
+
+Before using any of these recipes, ensure you have:
+
+* [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html){target="_blank"} configured
+* Python 3.10+ installed
+* Your preferred build tool installed (see individual recipes)
+
+## Choosing the right tool
+
+Each build tool has its strengths and is optimized for different use cases. Consider your project complexity, team preferences, and deployment requirements when selecting the best approach.
+
+| Tool                  | Best for                          | Considerations                              |
+| --------------------- | --------------------------------- | ------------------------------------------- |
+| **[pip](build-with-pip.md)**       | Simple projects, CI/CD            | Lightweight, universal                      |
+| **[poetry](build-with-poetry.md)** | Modern Python projects            | Excellent dependency management, lock files |
+| **[uv](build-with-uv.md)**         | Fast builds, performance-critical | Extremely fast, Rust-based                  |
+| **[pants](build-with-pants.md)**   | Monorepos, complex projects       | Advanced build system, incremental builds   |
+| **[SAM](build-with-sam.md)**       | AWS-native deployments            | Integrated with AWS, local testing          |
+| **[CDK](build-with-cdk.md)**       | Infrastructure as code            | Programmatic infrastructure, type safety    |
+
+???+ tip
+    All examples in this guide are available in the [project repository](https://github.com/aws-powertools/powertools-lambda-python/tree/develop/examples/build_recipes){target="_blank"}.

docs/build_recipes/index.md

@@ -0,0 +1,57 @@
+---
+title: Build Recipes
+description: Lambda function packaging recipes with Powertools for AWS
+---
+
+<!-- markdownlint-disable MD043 MD013 -->
+
+As the Python ecosystem continues to evolve with new package managers, build tools, and dependency resolution strategies, choosing the right approach for Lambda deployments has become increasingly complex. Modern Python applications often involve compiled extensions, platform-specific dependencies, and sophisticated toolchains that require careful consideration for serverless environments.
+
+This guide provides practical recipes for packaging Lambda functions with Powertools for AWS Lambda (Python) using different build tools and dependency managers.
+
+## Key benefits
+
+* **Optimized packaging** - Reduce deployment package size and cold start times
+* **Dependency management** - Handle complex dependency trees efficiently
+* **Build reproducibility** - Consistent builds across environments
+* **Layer optimization** - Leverage Lambda Layers for better performance
+* **Multi-tool support** - Choose the right tool for your workflow
+
+## Terminology
+
+Understanding these key terms will help you navigate the build recipes more effectively:
+
+| Term | Definition |
+|------|------------|
+| **Deployment Package** | A ZIP archive or container image containing your Lambda function code and all its dependencies, ready for deployment to AWS Lambda |
+| **Lambda Layer** | A ZIP archive containing libraries, custom runtimes, or other function dependencies that can be shared across multiple Lambda functions |
+| **Build Tool** | Software that automates the process of compiling, packaging, and preparing your code for deployment (e.g., pip, poetry, uv, pants) |
+| **Dependency Manager** | Tool responsible for resolving, downloading, and managing external libraries your project depends on |
+| **Lock File** | A file that records the exact versions of all dependencies used in your project, ensuring reproducible builds (e.g., poetry.lock, uv.lock) |
+| **Cold Start** | The initialization time when AWS Lambda creates a new execution environment for your function, including loading your deployment package |
+| **SAM (Serverless Application Model)** | AWS framework for building serverless applications, providing templates and CLI tools for deploying Lambda functions and related resources |
+| **CDK (Cloud Development Kit)** | AWS framework for defining cloud infrastructure using familiar programming languages, enabling infrastructure as code for Lambda deployments |
+
+## Guide sections
+
+This guide is organized into focused sections to help you find exactly what you need:
+
+### 📚 Fundamentals
+
+* **[Getting started](getting-started.md)** - Prerequisites, tool selection, and basic setup
+* **[Cross-platform builds](cross-platform.md)** - Handle architecture differences and compiled dependencies
+
+### 🔧 Build tools
+
+* **[Build with pip](build-with-pip.md)** - Simple, universal package management
+* **[Build with Poetry](build-with-poetry.md)** - Modern dependency management with lock files
+* **[Build with uv](build-with-uv.md)** - Extremely fast Rust-based package manager
+* **[Build with SAM](build-with-sam.md)** - AWS Serverless Application Model integration
+* **[Build with CDK](build-with-cdk.md)** - Infrastructure as code with type safety
+* **[Build with Pants](build-with-pants.md)** - Advanced build system for monorepos
+
+### ⚡ Advanced topics
+
+* **[Performance optimization](performance-optimization.md)** - Reduce cold starts and package size
+* **[CI/CD integration](cicd-integration.md)** - Automate builds with GitHub Actions and CodeBuild
+* **[Troubleshooting](troubleshooting.md)** - Common issues and solutions

mkdocs.yml

@@ -9,11 +9,9 @@ nav:
   - Homepage:
       - index.md
       - Changelog: changelog.md
-      - API reference: api/" target="_blank
-      - Upgrade guide: upgrade.md
-      - We Made This (Community): we_made_this.md
+      - Tutorial: tutorial/index.md
       - Workshop 🆕: https://s12d.com/powertools-for-aws-lambda-workshop" target="_blank
-      - Roadmap: roadmap.md
+      - API reference: api/" target="_blank
       - Features:
           - core/tracer.md
           - core/logger.md
@@ -40,10 +38,16 @@ nav:
           - utilities/middleware_factory.md
           - utilities/jmespath_functions.md
           - CloudFormation Custom Resources: https://github.com/aws-cloudformation/custom-resource-helper" target="_blank
+      - Build recipes:
+          - build_recipes/index.md
+          - Getting started: build_recipes/getting-started.md
+      - Upgrade guide: upgrade.md
+      - We Made This (Community): we_made_this.md
+      - Roadmap: roadmap.md
       - Resources:
           - "llms.txt": ./llms.txt
           - "llms.txt (full version)": ./llms-full.txt
-  - Tutorial: tutorial/index.md
+
   - Processes:
       - Security: security.md
       - Automation: automation.md
@@ -233,6 +237,9 @@ plugins:
           - utilities/jmespath_functions.md
         Tutorial:
           - tutorial/index.md
+        Build recipes:
+          - build_recipes/index.md
+          - build_recipes/getting-started.md
 
   - mkdocstrings:
       default_handler: python