docs: consistency around admonitions and snippets (aws-powertools#919)

Co-authored-by: heitorlessa <[email protected]>

Author: DanyC97

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

@@ -27,10 +27,10 @@ You must have an existing AppSync GraphQL API and IAM permissions to invoke your
 
 This is the sample infrastructure we are using for the initial examples with a AppSync Direct Lambda Resolver.
 
-=== "schema.graphql"
+???+ tip "Tip: Designing GraphQL Schemas for the first time?"
+    Visit [AWS AppSync schema documentation](https://docs.aws.amazon.com/appsync/latest/devguide/designing-your-schema.html){target="_blank"} for understanding how to define types, nesting, and pagination.
 
-    !!! tip "Designing GraphQL Schemas for the first time?"
-        Visit [AWS AppSync schema documentation](https://docs.aws.amazon.com/appsync/latest/devguide/designing-your-schema.html){target="_blank"} for understanding how to define types, nesting, and pagination.
+=== "schema.graphql"
 
     ```typescript
     --8<-- "docs/shared/getting_started_schema.graphql"
@@ -176,7 +176,8 @@ You can define your functions to match GraphQL types and fields with the `app.re
 
 Here's an example where we have two separate functions to resolve `getTodo` and `listTodos` fields within the `Query` type. For completion, we use Scalar type utilities to generate the right output based on our schema definition.
 
-!!! info "GraphQL arguments are passed as function arguments"
+???+ info
+    GraphQL arguments are passed as function arguments.
 
 === "app.py"
 
@@ -395,69 +396,65 @@ You can nest `app.resolver()` decorator multiple times when resolving fields wit
 
 For Lambda Python3.8+ runtime, this utility supports async functions when you use in conjunction with `asyncio.run`.
 
-=== "async_resolver.py"
-
-    ```python hl_lines="4 8 10-12 20"
-    from aws_lambda_powertools import Logger, Tracer
+```python hl_lines="4 8 10-12 20" title="Resolving GraphQL resolvers async"
+from aws_lambda_powertools import Logger, Tracer
 
-    from aws_lambda_powertools.logging import correlation_paths
-    from aws_lambda_powertools.event_handler import AppSyncResolver
+from aws_lambda_powertools.logging import correlation_paths
+from aws_lambda_powertools.event_handler import AppSyncResolver
 
-    tracer = Tracer(service="sample_resolver")
-    logger = Logger(service="sample_resolver")
-    app = AppSyncResolver()
+tracer = Tracer(service="sample_resolver")
+logger = Logger(service="sample_resolver")
+app = AppSyncResolver()
 
-    @app.resolver(type_name="Query", field_name="listTodos")
-    async def list_todos():
-        todos = await some_async_io_call()
-        return todos
+@app.resolver(type_name="Query", field_name="listTodos")
+async def list_todos():
+	todos = await some_async_io_call()
+	return todos
 
-    @logger.inject_lambda_context(correlation_id_path=correlation_paths.APPSYNC_RESOLVER)
-    @tracer.capture_lambda_handler
-    def lambda_handler(event, context):
-        result = app.resolve(event, context)
+@logger.inject_lambda_context(correlation_id_path=correlation_paths.APPSYNC_RESOLVER)
+@tracer.capture_lambda_handler
+def lambda_handler(event, context):
+	result = app.resolve(event, context)
 
-        return asyncio.run(result)
-    ```
+	return asyncio.run(result)
+```
 
 ### Amplify GraphQL Transformer
 
 Assuming you have [Amplify CLI installed](https://docs.amplify.aws/cli/start/install){target="_blank"}, create a new API using `amplify add api` and use the following GraphQL Schema.
 
 <!-- AppSync resolver decorator is a concise way to create lambda functions to handle AppSync resolvers for multiple `typeName` and `fieldName` declarations. -->
 
-=== "schema.graphql"
-
-    ```typescript hl_lines="7 15 20 22"
-    @model
-    type Merchant {
-        id: String!
-        name: String!
-        description: String
-        # Resolves to `common_field`
-        commonField: String  @function(name: "merchantInfo-${env}")
-    }
-
-    type Location {
-        id: ID!
-        name: String!
-        address: String
-        # Resolves to `common_field`
-        commonField: String  @function(name: "merchantInfo-${env}")
-    }
-
-    type Query {
-      # List of locations resolves to `list_locations`
-      listLocations(page: Int, size: Int): [Location] @function(name: "merchantInfo-${env}")
-      # List of locations resolves to `list_locations`
-      findMerchant(search: str): [Merchant] @function(name: "searchMerchant-${env}")
-    }
-    ```
+```typescript hl_lines="7 15 20 22" title="Example GraphQL Schema"
+@model
+type Merchant {
+	id: String!
+	name: String!
+	description: String
+	# Resolves to `common_field`
+	commonField: String  @function(name: "merchantInfo-${env}")
+}
+
+type Location {
+	id: ID!
+	name: String!
+	address: String
+	# Resolves to `common_field`
+	commonField: String  @function(name: "merchantInfo-${env}")
+}
+
+type Query {
+  # List of locations resolves to `list_locations`
+  listLocations(page: Int, size: Int): [Location] @function(name: "merchantInfo-${env}")
+  # List of locations resolves to `list_locations`
+  findMerchant(search: str): [Merchant] @function(name: "searchMerchant-${env}")
+}
+```
 
 [Create two new basic Python functions](https://docs.amplify.aws/cli/function#set-up-a-function){target="_blank"} via `amplify add function`.
 
-!!! note "Amplify CLI generated functions use `Pipenv` as a dependency manager"
-    Your function source code is located at **`amplify/backend/function/your-function-name`**.
+???+ note
+    Amplify CLI generated functions use `Pipenv` as a dependency manager. Your function source code is located at **`amplify/backend/function/your-function-name`**.
 
 Within your function's folder, add Lambda Powertools as a dependency with `pipenv install aws-lambda-powertools`.
 
@@ -713,7 +710,8 @@ You can subclass `AppSyncResolverEvent` to bring your own set of methods to hand
 
 ### Split operations with Router
 
-!!! tip "Read the **[considerations section for trade-offs between monolithic and micro functions](./api_gateway.md#considerations){target="_blank"}**, as it's also applicable here."
+???+ tip
+    Read the **[considerations section for trade-offs between monolithic and micro functions](./api_gateway.md#considerations){target="_blank"}**, as it's also applicable here.
 
 As you grow the number of related GraphQL operations a given Lambda function should handle, it is natural to split them into separate files to ease maintenance - That's where the `Router` feature is useful.