docs(parser): change parser documentation

[anafalcao]

Issue number: #1371

Summary

This PR refreshes Parser docs with newer features like examples, improves wording and navigation, focused on Powertools v3.

Changes

• Clean up the initial explanation
• Clean up Key Features
• Move the info "this is not necessary if using Layers" to the top
• Remove Pydantic 1 integration
• Add a QuickStart with BaseModels and Parse events
• Add sections Getting Started and Advanced
• Fix the parse() function example and initial explanation
• Add differences between of parse() and event_parser
• Clean up the example of extending built-in models; add pre and post explanations
• Clean up the Envelopes example and improve the initial explanation
• Complete the Validating fields example
• Clean up the root_validator example
• Move the Pydantic helper functions box to Getting started section
• Restructure Serialization; add a functional example
• Clean up the two examples of string fields that contain JSON data
• Clean up the Bringing your own envelope examples

User experience

Please share what the user experience looks like before and after this change

Checklist

If your change doesn't seem to apply, please leave them unchecked.

• Meet tenets criteria
• I have performed a self-review of this change
• Changes have been tested
• Changes are documented
• PR title follows conventional commit semantics

Is this a breaking change?

RFC issue number:

Checklist:

• Migration process documented
• Implement warnings (if it can live side by side)

Acknowledgment

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Disclaimer: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.

[boring-cyborg]

Thanks a lot for your first contribution! Please check out our contributing guidelines and don't hesitate to ask whatever you need.
In the meantime, check out the #python channel on our Powertools for AWS Lambda Discord: Invite link

[github-actions]

⚠️Large PR detected⚠️

Please consider breaking into smaller PRs to avoid significant review delays. Ignore if this PR has naturally grown to this size after reviews.

[anafalcao]

Hey @leandrodamascena !
Can you please review this PR? Something is missing for this issue #5390, and I may need some direction to fix it.
Thanks

[leandrodamascena]

Hey @anafalcao! This is amazing to start reviewing this PR, indeed a great improvement in our documentation.

I see we have room to improve some areas and I left some comments. Can you please review and address them before we move to the next round of this review?

[anafalcao]

Thank you so much for the reviews @leandrodamascena ! Fixed your comments

[leandrodamascena]

Thanks for addressing to all the feedback, @anafalcao! I have some new comments in this second round!

Lets go!! We're almost ready to merge this PR.

[github-actions]

⚠️Large PR detected⚠️

Please consider breaking into smaller PRs to avoid significant review delays. Ignore if this PR has naturally grown to this size after reviews.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 96.16%. Comparing base (4a4bf17) to head (4d10ff8).
Report is 1 commits behind head on develop.

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #5262   +/-   ##
========================================
  Coverage    96.16%   96.16%           
========================================
  Files          229      229           
  Lines        10810    10810           
  Branches      2007     2007           
========================================
  Hits         10395    10395           
  Misses         327      327           
  Partials        88       88           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[leandrodamascena]

Hi @anafalcao! Congratulations on getting your first PR approved as a Powertools maintainer, this is a huge achievement in such a short time. I made a few small changes before approving it and let me tell you:

1 - We try to use active voice as much as possible, so in areas where you were saying "parser allows you to use XYZ", I changed it to "you can use XYZ in the parser utility".

2 - Some examples were importing things from Powertools instead of Pydantic, as it is better to import BaseModel directly from Pydantic than from Powertools, for example. Both work, but the customer can have more control over the imports.

3 - Mypy was complaining about some types, but don't worry, mypy is a nightmare sometimes.

4 - Some highlights were wrong and I fixed them.

Congratss!! 🚀 ⭐

[dreamorosi]

Left a few comments.

Thanks a lot for the work on this PR!

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarCloud

[leandrodamascena]

Hi @dreamorosi! Thanks for such a detailed review, I pushed a new commit with the last few things before we merge.

[dreamorosi]

Great work @anafalcao, looking forward to see this merged.

We should probably bring these changes to the TS docs as well.

[boring-cyborg]

Awesome work, congrats on your first merged pull request and thank you for helping improve everyone's experience!