docs(api): migrating the event handler utility to mkdocstrings (aws-powertools#6023)

Mkdocstrings - Event handler

Author: leandrodamascena

Diff for: aws_lambda_powertools/event_handler/api_gateway.py

@@ -313,10 +313,10 @@ def __init__(
         middlewares: list[Callable[..., Response]] | None = None,
     ):
         """
+        Internally used Route Configuration
 
         Parameters
         ----------
-
         method: str
             The HTTP method, example "GET"
         path: str
@@ -908,6 +908,8 @@ def build(self, event: ResponseEventT, cors: CORSConfig | None = None) -> dict[s
 
 
 class BaseRouter(ABC):
+    """Base class for Routing"""
+
     current_event: BaseProxyEvent
     lambda_context: LambdaContext
     context: dict
@@ -1459,7 +1461,7 @@ def _registered_api_adapter(app: ApiGatewayResolver, next_middleware: Callable[.
 
 
 class ApiGatewayResolver(BaseRouter):
-    """API Gateway and ALB proxy resolver
+    """API Gateway, VPC Laticce, Bedrock and ALB proxy resolver
 
     Examples
     --------
@@ -2570,6 +2572,8 @@ def register_exception_handler(func: Callable):
 
 
 class APIGatewayRestResolver(ApiGatewayResolver):
+    """Amazon API Gateway REST and HTTP API v1 payload resolver"""
+
     current_event: APIGatewayProxyEvent
 
     def __init__(
@@ -2650,6 +2654,8 @@ def _compile_regex(rule: str, base_regex: str = _ROUTE_REGEX):
 
 
 class APIGatewayHttpResolver(ApiGatewayResolver):
+    """Amazon API Gateway HTTP API v2 payload resolver"""
+
     current_event: APIGatewayProxyEventV2
 
     def __init__(
@@ -2685,6 +2691,8 @@ def _get_base_path(self) -> str:
 
 
 class ALBResolver(ApiGatewayResolver):
+    """Amazon Application Load Balancer (ALB) resolver"""
+
     current_event: ALBEvent
 
     def __init__(

Diff for: aws_lambda_powertools/event_handler/middlewares/base.py

@@ -26,7 +26,7 @@ class BaseMiddlewareHandler(Generic[EventHandlerInstance], ABC):
     This is the middleware handler function where middleware logic is implemented.
     The next middleware handler is represented by `next_middleware`, returning a Response object.
 
-    Examples
+    Example
     --------
 
     **Correlation ID Middleware**

Diff for: aws_lambda_powertools/event_handler/middlewares/openapi_validation.py

@@ -37,7 +37,7 @@ class OpenAPIValidationMiddleware(BaseMiddlewareHandler):
     Lambda handler. It also validates the response against the OpenAPI schema defined by the Lambda handler. It
     should not be used directly, but rather through the `enable_validation` parameter of the `ApiGatewayResolver`.
 
-    Examples
+    Example
     --------
 
     ```python

Diff for: aws_lambda_powertools/event_handler/middlewares/schema_validation.py

@@ -18,7 +18,7 @@
 class SchemaValidationMiddleware(BaseMiddlewareHandler):
     """Middleware to validate API request and response against JSON Schema using the [Validation utility](https://docs.powertools.aws.dev/lambda/python/latest/utilities/validation/).
 
-    Examples
+    Example
     --------
     **Validating incoming event**
 

Diff for: aws_lambda_powertools/event_handler/openapi/params.py

@@ -879,8 +879,6 @@ def get_flat_dependant(
     ----------
     dependant: Dependant
         The dependant model to flatten
-    skip_repeats: bool
-        If True, child Dependents already visited will be skipped to avoid duplicates
     visited: list[CacheKey], optional
         Keeps track of visited Dependents to avoid infinite recursion. Defaults to empty list.
 
@@ -932,8 +930,9 @@ def analyze_param(
     ModelField | None
         The type annotation and the Pydantic field representing the parameter
     """
-    field_info, type_annotation = \
-        get_field_info_and_type_annotation(annotation, value, is_path_param, is_response_param)
+    field_info, type_annotation = get_field_info_and_type_annotation(
+        annotation, value, is_path_param, is_response_param,
+    )
 
     # If the value is a FieldInfo, we use it as the FieldInfo for the parameter
     if isinstance(value, FieldInfo):
@@ -964,7 +963,7 @@ def analyze_param(
 
 
 def get_field_info_and_type_annotation(
-    annotation, value, is_path_param: bool, is_response_param: bool
+    annotation, value, is_path_param: bool, is_response_param: bool,
 ) -> tuple[FieldInfo | None, Any]:
     """
     Get the FieldInfo and type annotation from an annotation and value.

Diff for: aws_lambda_powertools/event_handler/openapi/swagger_ui/html.py

@@ -22,7 +22,7 @@ def generate_swagger_html(
     spec: str
         The OpenAPI spec
     swagger_js: str
-       Swagger UI JavaScript source code or URL
+        Swagger UI JavaScript source code or URL
     swagger_css: str
         Swagger UI CSS source code or URL
     swagger_base_url: str

Diff for: aws_lambda_powertools/logging/exceptions.py

@@ -2,4 +2,5 @@ class InvalidLoggerSamplingRateError(Exception):
     """
     Logger configured with Invalid Sampling value
     """
+
     pass

Diff for: aws_lambda_powertools/logging/logger.py

@@ -3,6 +3,7 @@
 !!! abstract "Usage Documentation"
     [`Logger`](../../core/logger.md)
 """
+
 from __future__ import annotations
 
 import functools

Diff for: aws_lambda_powertools/metrics/provider/datadog/datadog.py

@@ -87,10 +87,6 @@ def add_metric(
             Timestamp in int for the metrics, default = time.time()
         tags: list[str]
             In format like ["tag:value", "tag2:value2"]
-        args: Any
-            extra args will be dropped for compatibility
-        kwargs: Any
-            extra kwargs will be converted into tags, e.g., add_metrics(sales=sam) -> tags=['sales:sam']
 
         Examples
         --------

Diff for: aws_lambda_powertools/tracing/base.py

@@ -3,6 +3,7 @@
 !!! abstract "Usage Documentation"
     [`Tracer`](../../core/tracer.md)
 """
+
 from __future__ import annotations
 
 import abc

Diff for: docs/api_doc/event_handler/api_gateway.md

@@ -0,0 +1,2 @@
+<!-- markdownlint-disable MD043 MD041 -->
+::: aws_lambda_powertools.event_handler.api_gateway

Diff for: docs/api_doc/event_handler/appsync.md

@@ -0,0 +1,2 @@
+<!-- markdownlint-disable MD043 MD041 -->
+::: aws_lambda_powertools.event_handler.appsync

Diff for: docs/api_doc/event_handler/middleware.md

@@ -0,0 +1,2 @@
+<!-- markdownlint-disable MD043 MD041 -->
+::: aws_lambda_powertools.event_handler.middlewares

Diff for: docs/api_doc/event_handler/openapi.md

@@ -0,0 +1,2 @@
+<!-- markdownlint-disable MD043 MD041 -->
+::: aws_lambda_powertools.event_handler.openapi

Diff for: mkdocs.yml

@@ -72,6 +72,11 @@ nav:
           - Base: api_doc/data_masking/base.md
           - Exception: api_doc/data_masking/exceptions.md
           - Provider: api_doc/data_masking/provider.md
+      - Event Handler:
+          - AppSync: api_doc/event_handler/appsync.md
+          - Middleware: api_doc/event_handler/middleware.md
+          - OpenAPI: api_doc/event_handler/openapi.md
+          - REST: api_doc/event_handler/api_gateway.md
       - Feature Flags:
           - AppConfig: api_doc/feature_flags/appconfig.md
           - Base: api_doc/feature_flags/base.md