docs(idempotency): improve navigation, wording, and new section on guarantees

[heitorlessa]

Issue number: #4197

Summary

This PR refreshes Idempotency docs with newer features like cards, improves wording and navigation from ServerlessDays ANZ feedback, and add a new section to call out guarantees/caveats upfront.

Changes

Please provide a summary of what's being changed

• [ ] Create Guarantee or Caveats section
• [x] Cover IdempotencyValidationError in code snippet
• [x] Fix links no longer exist/renamed
• [x] Move expiring records to getting started (rename it too)
• [x] Move composite key under DDB persistence layer
• [x] Common use cases / Compatibility seems to be duplicated
• [x] Fix examples not using table env var (most are hardcoded)
• [x] cleanup intro and key features
• [x] cleanup getting started ddb vs redis
• [x] break iam permissions into table; IAM permission to clipboard
• [x] cleanup dynamodb required resource; break subsections and update nav
• [x] cleanup redis usage and link with setup/infra
• [x] make terminologies crispier
• [x] line editing before decorators
• [x] cleanup idempotent decorator; inline admonitions
• [x] cleanup idempotent_decorator section
• [x] cleanup serialization, fields subset, move batch to new common use case section
• [x] cleanup timeout section
• [x] use cards for required resources to showcase DDB and Redis better
• [x] note to skip timeout section when using handler decorator
• [x] remove tabbed content for single timeout snippet
• [x] cleanup handling exceptions
• [x] cleanup persistence layers attrs, snippet titles etc
• [x] typo in batch integration
• [x] rename batch integration to actual use case name
• [x] cleanup default behavior section
• [x] add ability to dismiss announcement
• [x] move bold to draw attention to whole event as idempotency key
• [x] move caching to getting started
• [x] fix redis example parameters typing
• [x] fix batch example using newer mechanism (simpler)
• [x] fix local cache example to use powertools_json as it was incorrect

Unrelated

• [x] navigation: add social links
• [x] navigation: allow returning customers to dismiss announcement banner
• [x] navigation: increase table of contents depth to 5 to help redis and other subsections

Tech Debt

• [ ] New method to more easily calculate remaining time (-> datetime) for customers using response hooks (e.g., Event Handler middleware)

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.

• [x] Meet tenets criteria
• [x] I have performed a self-review of this change
• [x] Changes have been tested
• [x] Changes are documented
• [x] 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.

[heitorlessa]

mypy is failing after correcting snippets; will look at that last as there's one major piece of doc to create yet

[leandrodamascena]

Hey @heitorlessa! 90% of the errors are related to the table_name variable.

Argument "table_name" to "DynamoDBPersistenceLayer" has incompatible type "str | None"; expected "str"

This is because the DynamoDBPersistenceLayer class doesnt accept None for table_name parameter and the default return for os.getenv is None when it don't find the env variable.

I think we can do this: table = os.getenv("IDEMPOTENCY_TABLE", "")

WDYT?

[codecov[bot]]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 96.45%. Comparing base (e14e768) to head (6a0364d). Report is 679 commits behind head on develop.

Additional details and impacted files

```diff @@ Coverage Diff @@ ## develop #4613 +/- ## =========================================== + Coverage 96.38% 96.45% +0.07% =========================================== Files 214 223 +9 Lines 10030 10728 +698 Branches 1846 1996 +150 =========================================== + Hits 9667 10348 +681 - Misses 259 268 +9 - Partials 104 112 +8 ```

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.