docs(validation): snippets split, improved, and lint

[leandrodamascena]

Issue number: #1370

Summary

Changes

Changes snippet fictitious names to real code snippet filenames for easier discovery and collaboration to improve/correct document snippets.

Some examples have also been refactored so that the codes are complete and there are no lint/pre-commit hooks issues.

User experience

Before:

After:

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.

---

View rendered docs/utilities/jmespath_functions.md
View rendered docs/utilities/validation.md

[heitorlessa]

@leandrodamascena could you rebase and fix the conflicts?

[leandrodamascena]

@leandrodamascena could you rebase and fix the conflicts?

Yep! Gimme some minutes and I do this.

[heitorlessa]

Looks great - thank you!! Made some quick fixes to speed up for merging. The only change pending is to rethink the username/password sample.

One thing you'll notice in the quick changes is the highlight. We need to be mindful of people's eyesight with an accidental excessive highlight - only highlight the absolute parts you're trying to show them about X example. For example, highlight the SchemaValidationError not all other exceptions.

[heitorlessa]

rethink username/password snippet

[leandrodamascena]

rethink username/password snippet

I refactored this piece of code and added a integration with the Parameter utility to get data from there and raise the bar in this example. Please check if it's ok now.

Thanks for advising me on the highlights mindset. It really makes a lot of sense not to add too many highlights and make the user journey hard.

[rubenfonseca]

Hi @leandrodamascena this looks great to me. The only concern I share is too much highlighting when browsing the docs, but I guess you already working on that. Can you ping me again when you finish the changes?

[rubenfonseca]

Lovely job! Thank you!

[rubenfonseca]

Not sure why CI/CD didn't run here? I would love to have mypy check the samples for errors before merging

[leandrodamascena]

Not sure why CI/CD didn't run here? I would love to have mypy check the samples for errors before merging

Well.. mypy and other checks are working fine locally

[codecov-commenter]

Codecov Report

Merging #1449 (49be843) into develop (d989028) will increase coverage by 0.00%.
The diff coverage is n/a.

@@           Coverage Diff            @@
##           develop    #1449   +/-   ##
========================================
  Coverage    99.89%   99.89%           
========================================
  Files          121      123    +2     
  Lines         5479     5496   +17     
  Branches       627      629    +2     
========================================
+ Hits          5473     5490   +17     
  Misses           2        2           
  Partials         4        4           

Impacted Files	Coverage Δ
...bda_powertools/utilities/parser/models/__init__.py	100.00% <0.00%> (ø)
..._powertools/utilities/parser/envelopes/__init__.py	100.00% <0.00%> (ø)
...ols/utilities/parser/models/lambda_function_url.py	100.00% <0.00%> (ø)
.../utilities/parser/envelopes/lambda_function_url.py	100.00% <0.00%> (ø)

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.