Docs: Move code snippets into dedicated python files add formatting and linting, fixing any outstanding errors

[michaelbrewer]

Is your feature request related to a problem? Please describe.

• Docs: HomePage - terraform example has a syntax error #1067
• Docs: Event Handler - Broken AWS Serverless Application Model (SAM) example #1069
• Docs: HomePage - Least-privileged IAM permissions to deploy Layer has syntax errors #1207
• Docs: Batch - Testing your code examples has syntax errors #1211
• Docs: Metrics - Assert multiple EMF blobs with pytest has invalid python syntax #1212
• Docs: Metrics - Invalid AWS Serverless Application Model (SAM) example #1213
• Docs: JMESPath - python syntax error in custom_jmespath_function.py #1214
• Docs: Logger - Cloning Logger config to all other registered standard loggers example has errors #1215
• Docs: Idempotency - Exception not affecting idempotency record sample example has python syntax errors #1216
• Docs: Idempotency - Syntax error in Reusing a DynamoDB table that uses a composite primary key example #1217
• Docs: Event Handler - Rest API - Example response.json in fined grained responses not formatted correctly #1223
• or see Additional context for a summary

Describe the solution you'd like

In the past there was many documentation errors found like #1004 , on a regular basis i would try to help the
community by verifying the code examples, that they can compile, linted, valid formatting and had the correct line highlights

As part of general papercuts #857 and then later #1009 it was decided to split up the examples into separate files so that they can be linted or validates.

Currently the AWS Lambda Documentation has many typos, syntax errors, missing imports, invalid yaml indentation and terraform errors (about 25 errors currently and we keeping on running into this errors each time code examples are updated or added (see #1004). Here is a list of some of them as separate issues:

Hosted version of this is at: https://gyft.github.io/aws-lambda-powertools-python/latest/

Describe alternatives you've considered

Keeping the examples inside the markdown docs. But we run into issues like below, where errors are not easily picked up

Additional context

As a side effect many existing errors will be resolved AND measures put in to prevent them from happening again. Here is a list of errors currently in the documentation

• Includes fix(docs): fix syntax errors in the lambda layer terraform example #1068 HomePage - Lambda Layer - Terraform example
• Fix python syntax HomePage - SAR - CDK examples
• Fix template yml indents HomePage - Example: Least-privileged IAM permissions to deploy Layer example
• Open external links in a new tab for Tracer - page
• Fix example in Logger - FAQ section Cloning Logger config to all other registered standard loggers which results in a error AttributeError: module 'logging' has no attribute 'logger' on line 8
• Fix metrics SAM Metrics - template.yml indents
• Fix missing imports for Metrics - Clear metrics tests
• Fix python syntax on Metrics - Assert multiple EMF blobs with pytest example
• Fix SAM example for Rest api (and fixes Docs: Event Handler - Broken AWS Serverless Application Model (SAM) example #1069) REST API : Required resources
• Fix json response example in Rest API - Fine grained response - Not formatted as json
• Fix missing import for Parameters - Creating a S3 Provider to fetch parameters example
• Fix examples in Batch - Pydantic integration
• Clean up Batch - Accessing processed messages via context manager example removing unused imports and fix line highlights.
• Fix missing imports in Batch - Extending failure handling mechanism in BatchProcessor example
• Fix python syntax errors in Batch -Testing your code examples
• Fix missing parameter in success_handler Batch - Creating a custom batch processor example
• Fix import for Batch - Customizing boto configuration example
• Fix name for validator_function.py example, see Validation - Validate function
• Fix ht_line invalid syntax in Validation - Validating custom formats - schema.py
• Fix missing imports for Parser - EventBridge Envelope example
• Fix yaml indent in Idempotency -AWS Serverless Application Model (SAM) example
• Fix python syntax in Idempotency - Exception not affecting idempotency record sample example
• Fix python syntax in Idempotency - Reusing a DynamoDB table that uses a composite primary key example
• Fix python syntax in Idempotency - Using Idempotency with JSONSchema Validation utility example
• Fix Deserializing JSON before using as idempotency key example in JMESPath Functions - page - Missing import
• Fix custom_jmespath_function.py example in JMESPath Functions - page - Invalid python syntax

List of open pull requests

Originally part of a simple PR #1065 but now split up into smaller ones

• docs(home): extract and fix examples #1113
• docs(tutorial): extract code examples #1137
• docs(tracer): extract code examples #1126
• docs(logger): extract and fix code examples #1121
• docs(metrics): extract and fix code examples #1122
• docs(event-handler): extract and fix REST code examples #1117
• docs(event-handler): extract GraphQL code examples #1116
• docs(middleware): extract code examples #1123
• docs(parameters): extract and fix code examples #1124
• docs(batch): extract and fix examples #1114
• docs(typing): extract code examples #1127
• docs(validation): extract and fix code examples #1128
• docs(event-sources): extract examples #1115
• docs(parser): extract and fix code examples #1125
• docs(idempotency): extract and fix code examples #1119
• docs(feature-flags): extract code examples #1118
• docs(jmespath): extract and fix code examples #1120

[michaelbrewer]

I have a pull request that partially fixes this (as there is a lot of examples to migrate). So once there is feedback on this I can continue.

[michaelbrewer]

@heitorlessa @sthulb - as part of the original papercuts, we had discuss how many errors we have fund in the code examples, and that extracting them into separate files would allow us to add formatting (isort, black), check for syntax error (py_compile) and perform linting (cfn-lint etc..).

So in a series of pull requests, i have extracted and fixes all of the code examples (python, terraform and sam templates) and fixed (over 25 errors so far). Some of these pull requests has quite a few errors and some just have smaller formatting inconsistencies.

[sthulb]

The pull requests associated with this issue will be resolved eventually. There’s a lot of them and they’re quite large too.

[michaelbrewer]

Yep and covers 25 error in the docs too

[michaelbrewer]

Updated preview of fixed docs is hosted here: https://gyft.github.io/aws-lambda-powertools-python/latest/

Up to version 1.25.10

[michaelbrewer]

@sthulb i have adding all of the missing bug reports for syntax errors identified from this task.

[michaelbrewer]

Updated preview of fixed docs is hosted here: gyft.github.io/aws-lambda-powertools-python/latest

Up to version 1.26.1

[github-actions]

Comments on closed issues are hard for our team to see.