Revamp Data Classes utility docs to surface many unknown features

[heitorlessa]

What were you initially searching for in the docs?

Use cases like fetching HTTP Headers from either API Gateway REST & HTTP API, ALB, AppSync in a case insensitive way is covered by get_header_value, but it's nearly hidden in the documentation.

That goes on with S3 unquote plus, multiple SES utilities, encoding/decoding methods, etc.

Is this related to an existing part of the documentation? Please share a link

https://awslabs.github.io/aws-lambda-powertools-python/utilities/data_classes

Describe how we could make it clearer*

• A sub-section for each Dataclass of common scenarios
• A link to API docs for people to know what properties are available beyond most common use cases
• Revamp Dataclass API for each supported dataclass to have examples like we do in Core and some others https://awslabs.github.io/aws-lambda-powertools-python/api/utilities/data_classes/index.html
• New Cookbook section in the docs covering many common paths when dealing with rich Event Sources

If you have a proposed update, please share it here

[michaelbrewer]

@heitorlessa - is there any pieces of this you would want me to help look into?

A link to API docs for people to know what properties are available beyond most common use cases

I could provide links to underlying api dates for each of the data classes from the docs?

[gwlester]

I agree, we had to go diving in the code to see what methods the DynamoDb Stream Event (and the classes it uses) had.

I may have even missed some that caused me to open a Feature Request here.

[heitorlessa]

@gwlester I'm sorry to hear you had to resort to that, that's not the experience we want to provide.

This is the direct link to the API docs: https://awslabs.github.io/aws-lambda-powertools-python/develop/api/utilities/data_classes/dynamo_db_stream_event.html

After 1.17.0 release this coming week during business hours, I'll drop all else to revamp this doc.

@michaelbrewer for now, a table of all methods along with a description suffice.

I'll recreate this doc from
scratch, have each event source with its own sub-page with complete examples, a link to API reference, and revisit constructor docstring example section.

This might take up to two weeks and PRs will link here to help follow its progress

[gwlester]

FYI I started from https://awslabs.github.io/aws-lambda-powertools-python/latest/ -- no rush.

BTW, we LOVE this package!!!!

[michaelbrewer]

Maybe there is a better way to integrate the docs and the api docs?

[heitorlessa]

I'm gonna give mkdocstrings another try. This would include API docs with native anchors and structure - last time I tried I didn't have enough time to tune settings and docstrings to better fit in the current structure we have.

[heitorlessa]

Giving mkdocstrings a try today, will post the results here later

[heitorlessa]

Update: Bumped into handler bugs in mkdocstrings not recognizing custom sections in numpy docstrings, then got later deprioritized due to bandwidth to focus on bug fixing other areas.

[github-actions]

⚠️COMMENT VISIBILITY WARNING⚠️

This issue is now closed. Please be mindful that future comments are hard for our team to see.

If you need more assistance, please either tag a team member or open a new issue that references this one.

If you wish to keep having a conversation with other community members under this issue feel free to do so.