docs(typing): snippets split, improved, and lint (#1465)

Co-authored-by: Ruben Fonseca <fonseka@gmail.com>
Co-authored-by: Heitor Lessa <lessa@amazon.com>

Author: 3 people

docs/media/utilities_typing.png

@@ -7,17 +7,40 @@ description: Utility
 
 This typing utility provides static typing classes that can be used to ease the development by providing the IDE type hints.
 
-![Utilities Typing](../media/utilities_typing.png)
+## Key features
+
+* Add static typing classes
+* Ease the development by leveraging your IDE's type hints
+* Avoid common typing mistakes in Python
+
+![Utilities Typing](../media/utilities_typing_1.png)
+
+## Getting started
+
+???+ tip
+    All examples shared in this documentation are available within the [project repository](https://github.com/awslabs/aws-lambda-powertools-python/tree/develop/examples){target="_blank"}.
+
+We provide static typing for any context methods or properties implemented by [Lambda context object](https://docs.aws.amazon.com/lambda/latest/dg/python-context.html){target="_blank"}.
 
 ## LambdaContext
 
 The `LambdaContext` typing is typically used in the handler method for the Lambda function.
 
-```python hl_lines="4" title="Annotating Lambda context type"
-from typing import Any, Dict
-from aws_lambda_powertools.utilities.typing import LambdaContext
+=== "getting_started_validator_decorator_function.py"
+
+	```python hl_lines="1 4"
+    --8<-- "examples/typing/src/getting_started_typing_function.py"
+	```
+
+## Working with context methods and properties
+
+Using `LambdaContext` typing makes it possible to access information and hints of all properties and methods implemented by Lambda context object.
+
+=== "working_with_context_function.py"
+
+	```python hl_lines="6 16 25 26"
+    --8<-- "examples/typing/src/working_with_context_function.py"
+	```
 
-def handler(event: Dict[str, Any], context: LambdaContext) -> Dict[str, Any]:
-	# Insert business logic
-	return event
-```
+![Utilities Typing All](../media/utilities_typing_2.png)
+![Utilities Typing Specific](../media/utilities_typing_3.png)

docs/media/utilities_typing_1.png

@@ -0,0 +1,6 @@
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+
+def handler(event: dict, context: LambdaContext) -> dict:
+    # Insert business logic
+    return event

docs/media/utilities_typing_2.png

@@ -0,0 +1,32 @@
+from time import sleep
+
+import requests
+
+from aws_lambda_powertools import Logger
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+logger = Logger()
+
+
+def lambda_handler(event, context: LambdaContext) -> dict:
+
+    limit_execution: int = 1000  # milliseconds
+
+    # scrape website and exit before lambda timeout
+    while context.get_remaining_time_in_millis() > limit_execution:
+
+        comments: requests.Response = requests.get("https://jsonplaceholder.typicode.com/comments")
+        # add logic here and save the results of the request to an S3 bucket, for example.
+
+        logger.info(
+            {
+                "operation": "scrape_website",
+                "request_id": context.aws_request_id,
+                "remaining_time": context.get_remaining_time_in_millis(),
+                "comments": comments.json()[:2],
+            }
+        )
+
+        sleep(1)
+
+    return {"message": "Success"}