docs(maintenance): update Middy sections (#1524)

dreamorosi · web-flow · commit 5cb016093248 · 2023-06-21T16:06:49.000+02:00
* fix: add back code copy button

* chore: clarify instrument clients

* docs: update middy info
diff --git a/docs/core/logger.md b/docs/core/logger.md
@@ -108,16 +108,19 @@ This functionality will include the following keys in your structured logs:
 
 === "Middy Middleware"
 
-    !!! tip "Using Middy for the first time?"
-        You can install Middy by running `npm i @middy/core`.
-        Learn more about [its usage and lifecycle in the official Middy documentation](https://middy.js.org/docs/intro/getting-started){target="_blank"}.
+    !!! tip "A note about Middy"
+        Currently we support only Middy `v3.x` that you can install it by running `npm i @middy/core@~3`.
+        Check their docs to learn more about [Middy and its middleware stack](https://middy.js.org/docs/intro/getting-started){target="_blank"} as well as [best practices when working with Powertools](https://middy.js.org/docs/integrations/lambda-powertools#best-practices){target="_blank"}.
 
     ```typescript hl_lines="1 13"
     --8<-- "docs/snippets/logger/middy.ts"
     ```
 
 === "Decorator"
 
+    !!! info
+        Decorators can only be attached to a class declaration, method, accessor, property, or parameter. Therefore, if you prefer to write your handler as a standard function rather than a Class method, use the middleware or the manual instrumentation instead. See the [official TypeScript documentation](https://www.typescriptlang.org/docs/handbook/decorators.html) for more details.
+
     ```typescript hl_lines="8"
     --8<-- "docs/snippets/logger/decorator.ts"
     ```
diff --git a/docs/core/metrics.md b/docs/core/metrics.md
@@ -195,9 +195,9 @@ You can add default dimensions to your metrics by passing them as parameters in
 
 === "Middy middleware"
 
-    !!! tip "Using Middy for the first time?"
-        You can install Middy by running `npm i @middy/core`.
-        Learn more about [its usage and lifecycle in the official Middy documentation](https://middy.js.org/docs/intro/getting-started){target="_blank"}.
+    !!! tip "A note about Middy"
+        Currently we support only Middy `v3.x` that you can install it by running `npm i @middy/core@~3`.
+        Check their docs to learn more about [Middy and its middleware stack](https://middy.js.org/docs/intro/getting-started){target="_blank"} as well as [best practices when working with Powertools](https://middy.js.org/docs/integrations/lambda-powertools#best-practices){target="_blank"}.
 
     ```typescript hl_lines="24-26"
     --8<-- "docs/snippets/metrics/defaultDimensionsMiddy.ts"
@@ -211,6 +211,9 @@ You can add default dimensions to your metrics by passing them as parameters in
 
 === "with logMetrics decorator"
 
+    !!! info
+        Decorators can only be attached to a class declaration, method, accessor, property, or parameter. Therefore, if you prefer to write your handler as a standard function rather than a Class method, use the middleware or the manual instrumentation instead. See the [official TypeScript documentation](https://www.typescriptlang.org/docs/handbook/decorators.html) for more details.
+
     ```typescript hl_lines="12"
     --8<-- "docs/snippets/metrics/defaultDimensionsDecorator.ts"
     ```
diff --git a/docs/core/tracer.md b/docs/core/tracer.md
@@ -85,22 +85,18 @@ You can quickly start by importing the `Tracer` class, initialize it outside the
 
 === "Middy Middleware"
 
-    !!! tip "Using Middy for the first time?"
-        You can install Middy by running `npm i @middy/core`.
-        Learn more about [its usage and lifecycle in the official Middy documentation](https://middy.js.org/docs/intro/getting-started){target="_blank"}.
+    !!! tip "A note about Middy"
+        Currently we support only Middy `v3.x` that you can install it by running `npm i @middy/core@~3`.
+        Check their docs to learn more about [Middy and its middleware stack](https://middy.js.org/docs/intro/getting-started){target="_blank"} as well as [best practices when working with Powertools](https://middy.js.org/docs/integrations/lambda-powertools#best-practices){target="_blank"}.
 
     ```typescript hl_lines="1 14 16"
     --8<-- "docs/snippets/tracer/middy.ts"
     ```
 
-    1. Using Middy for the first time? You can install Middy by running `npm i @middy/core`.
-       Learn more about [its usage and lifecycle in the official Middy documentation](https://github.com/middyjs/middy#usage){target="_blank"}.
-
 === "Decorator"
 
     !!! info
-        Decorators can only be attached to a class declaration, method, accessor, property, or parameter. Therefore, if you prefer to write your handler as a standard function rather than a Class method, use the middleware or the manual instrumentations instead.  
-        See the [official TypeScript documentation](https://www.typescriptlang.org/docs/handbook/decorators.html) for more details.
+        Decorators can only be attached to a class declaration, method, accessor, property, or parameter. Therefore, if you prefer to write your handler as a standard function rather than a Class method, use the middleware or the manual instrumentation instead. See the [official TypeScript documentation](https://www.typescriptlang.org/docs/handbook/decorators.html) for more details.
 
     ```typescript hl_lines="8"
     --8<-- "docs/snippets/tracer/decorator.ts"
diff --git a/docs/index.md b/docs/index.md
@@ -262,7 +262,7 @@ You can include Powertools for AWS Lambda (TypeScript) Lambda Layer using [AWS L
 
 You can instrument your code with Powertools for AWS Lambda (TypeScript) in three different ways:  
 
-* **Middy** middleware. It is the best choice if your existing code base relies on the [Middy](https://middy.js.org/docs/) middleware engine. Powertools for AWS Lambda (TypeScript) offers compatible Middy middleware to make this integration seamless.
+* **Middy** middleware. It is the best choice if your existing code base relies on the [Middy 3.x](https://middy.js.org/docs/) middleware engine. Powertools for AWS Lambda (TypeScript) offers compatible Middy middleware to make this integration seamless.
 * **Method decorator**. Use [TypeScript method decorators](https://www.typescriptlang.org/docs/handbook/decorators.html#method-decorators) if you prefer writing your business logic using [TypeScript Classes](https://www.typescriptlang.org/docs/handbook/classes.html). If you aren’t using Classes, this requires the most significant refactoring.
 * **Manually**. It provides the most granular control. It’s the most verbose approach, with the added benefit of no additional dependency and no refactoring to TypeScript Classes.
 
diff --git a/docs/snippets/tracer/captureAWS.ts b/docs/snippets/tracer/captureAWS.ts
@@ -2,4 +2,7 @@ import { S3 } from 'aws-sdk';
 import { Tracer } from '@aws-lambda-powertools/tracer';
 
 const tracer = new Tracer({ serviceName: 'serverlessAirline' });
-tracer.captureAWSClient(new S3());
+// Instrument the AWS SDK client
+const client = tracer.captureAWSClient(new S3());
+
+export default client;
diff --git a/docs/snippets/tracer/captureAWSAll.ts b/docs/snippets/tracer/captureAWSAll.ts
@@ -2,4 +2,10 @@ import { Tracer } from '@aws-lambda-powertools/tracer';
 import AWS from 'aws-sdk';
 
 const tracer = new Tracer({ serviceName: 'serverlessAirline' });
+
+// Instrument all AWS SDK clients created from this point onwards
 tracer.captureAWS(AWS);
+
+// Create a new client which will be automatically instrumented
+const client = new AWS.SecretsManager();
+export default client;
diff --git a/docs/snippets/tracer/captureAWSv3.ts b/docs/snippets/tracer/captureAWSv3.ts
@@ -2,4 +2,7 @@ import { SecretsManagerClient } from '@aws-sdk/client-secrets-manager';
 import { Tracer } from '@aws-lambda-powertools/tracer';
 
 const tracer = new Tracer({ serviceName: 'serverlessAirline' });
-tracer.captureAWSv3Client(new SecretsManagerClient({}));
+// Instrument the AWS SDK client
+const client = tracer.captureAWSv3Client(new SecretsManagerClient({}));
+
+export default client;
diff --git a/docs/snippets/tracer/middy.ts b/docs/snippets/tracer/middy.ts
@@ -1,5 +1,5 @@
 import { Tracer, captureLambdaHandler } from '@aws-lambda-powertools/tracer';
-import middy from '@middy/core'; // (1)
+import middy from '@middy/core';
 
 const tracer = new Tracer({ serviceName: 'serverlessAirline' });
 
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -43,6 +43,7 @@ theme:
     - navigation.indexes
     - navigation.tracking
     - content.code.annotate
+    - content.code.copy
     - toc.follow
     - toc.integrate
     - announce.dismiss
