Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Revamp Data Classes utility docs to surface many unknown features #1163

Open
Tracked by #1364
heitorlessa opened this issue Mar 17, 2021 · 8 comments
Open
Tracked by #1364

Revamp Data Classes utility docs to surface many unknown features #1163

heitorlessa opened this issue Mar 17, 2021 · 8 comments
Labels
documentation Improvements or additions to documentation event_sources Event Source Data Class utility

Comments

@heitorlessa
Copy link
Contributor

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*

If you have a proposed update, please share it here

@michaelbrewer
Copy link
Contributor

michaelbrewer commented Jun 5, 2021

@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
Copy link
Contributor

gwlester commented Jun 5, 2021

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
Copy link
Contributor Author

@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
Copy link
Contributor

gwlester commented Jun 5, 2021

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

BTW, we LOVE this package!!!!

@michaelbrewer
Copy link
Contributor

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

@heitorlessa
Copy link
Contributor Author

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
Copy link
Contributor Author

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

@heitorlessa heitorlessa transferred this issue from aws-powertools/powertools-lambda-python Nov 29, 2021
@heitorlessa
Copy link
Contributor Author

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation event_sources Event Source Data Class utility
Projects
Status: Backlog
Development

No branches or pull requests

3 participants