docs(tracer): split and lint code snippets (#1260)

Author: heitorlessa

Diff for: .github/workflows/python_docs.yml

@@ -8,6 +8,7 @@ on:
       - "docs/**"
       - "CHANGELOG.md"
       - "mkdocs.yml"
+      - "examples/**"
 
 jobs:
   docs:
@@ -20,10 +21,15 @@ jobs:
         uses: actions/setup-python@v4
         with:
           python-version: "3.8"
+      # Maintenance: temporarily until we drop Python 3.6 and make cfn-lint a dev dependency
+      - name: Setup Cloud Formation Linter with Latest Version
+        uses: scottbrenner/cfn-lint-action@v2
       - name: Install dependencies
         run: make dev
       - name: Lint documentation
-        run: make lint-docs
+        run: |
+          make lint-docs
+          cfn-lint examples/**/*.yaml
       - name: Setup doc deploy
         run: |
           git config --global user.name Docs deploy

Diff for: .pre-commit-config.yaml

@@ -30,9 +30,13 @@ repos:
         entry: poetry run flake8
         language: system
         types: [python]
-        exclude: example
   - repo: https://github.com/igorshubovych/markdownlint-cli
     rev: "11c08644ce6df850480d98f628596446a526cbc6" # frozen: v0.31.1
     hooks:
       - id: markdownlint
         args: ["--fix"]
+  - repo: https://github.com/aws-cloudformation/cfn-python-lint
+    rev: v0.61.1
+    hooks:
+      - id: cfn-python-lint
+        files: examples/.*\.(yaml|yml)$

Diff for: Makefile

@@ -10,11 +10,11 @@ dev:
 	pre-commit install
 
 format:
-	poetry run isort aws_lambda_powertools tests
-	poetry run black aws_lambda_powertools tests
+	poetry run isort aws_lambda_powertools tests examples
+	poetry run black aws_lambda_powertools tests examples
 
 lint: format
-	poetry run flake8 aws_lambda_powertools/* tests/*
+	poetry run flake8 aws_lambda_powertools tests examples
 
 lint-docs:
 	docker run -v ${PWD}:/markdown 06kellyjac/markdownlint-cli "docs"

Diff for: docs/core/tracer.md

@@ -20,33 +20,16 @@ Tracer is an opinionated thin wrapper for [AWS X-Ray Python SDK](https://github.
 
 Before your use this utility, your AWS Lambda function [must have permissions](https://docs.aws.amazon.com/lambda/latest/dg/services-xray.html#services-xray-permissions) to send traces to AWS X-Ray.
 
-```yaml hl_lines="6 9" title="AWS Serverless Application Model (SAM) example"
-Resources:
-  HelloWorldFunction:
-	Type: AWS::Serverless::Function
-	Properties:
-	  Runtime: python3.8
-	  Tracing: Active
-	  Environment:
-		Variables:
-		  POWERTOOLS_SERVICE_NAME: example
+```yaml hl_lines="9 12" title="AWS Serverless Application Model (SAM) example"
+--8<-- "examples/tracer/template.yaml"
 ```
 
 ### Lambda handler
 
 You can quickly start by initializing `Tracer` and use `capture_lambda_handler` decorator for your Lambda handler.
 
-```python hl_lines="1 3 6" title="Tracing Lambda handler with capture_lambda_handler"
-from aws_lambda_powertools import Tracer
-
-tracer = Tracer() # Sets service via env var
-# OR tracer = Tracer(service="example")
-
-@tracer.capture_lambda_handler
-def handler(event, context):
-	charge_id = event.get('charge_id')
-	payment = collect_payment(charge_id)
-	...
+```python hl_lines="1 4 12" title="Tracing Lambda handler with capture_lambda_handler"
+--8<-- "examples/tracer/src/capture_lambda_handler.py"
 ```
 
 `capture_lambda_handler` performs these additional tasks to ease operations:

Diff for: examples/tracer/src/capture_lambda_handler.py

@@ -0,0 +1,15 @@
+from aws_lambda_powertools import Tracer
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+tracer = Tracer()  # Sets service via POWERTOOLS_SERVICE_NAME env var
+# OR tracer = Tracer(service="example")
+
+
+def collect_payment(charge_id: str) -> str:
+    return f"dummy payment collected for charge: {charge_id}"
+
+
+@tracer.capture_lambda_handler
+def handler(event: dict, context: LambdaContext) -> str:
+    charge_id = event.get("charge_id")
+    return collect_payment(charge_id)

Diff for: examples/tracer/template.yaml

@@ -0,0 +1,23 @@
+AWSTemplateFormatVersion: "2010-09-09"
+Transform: AWS::Serverless-2016-10-31
+Description: AWS Lambda Powertools Tracer doc examples
+
+Globals:
+  Function:
+    Timeout: 5
+    Runtime: python3.9
+    Tracing: Active
+    Environment:
+      Variables:
+        POWERTOOLS_SERVICE_NAME: example
+    Layers:
+      # Find the latest Layer version in the official documentation
+      # https://awslabs.github.io/aws-lambda-powertools-python/latest/#lambda-layer
+      - !Sub arn:aws:lambda:${AWS::Region}:017000801446:layer:AWSLambdaPowertoolsPython:21
+
+Resources:
+  CaptureLambdaHandlerExample:
+    Type: AWS::Serverless::Function
+    Properties:
+      CodeUri: src
+      Handler: capture_lambda_handler.handler