aws-powertools/powertools-lambda-python

Docs: Parameters / SSM Provider / recursive parameters snippet has incorrect highlighting

Closed this issue · 4 comments

ConnorKirk commented

What were you searching in the docs?

//

Is this related to an existing documentation section?

No response

How can we improve?

The snippet highlighting seems wrong. It is highlighting the creation of a boto session, rather than the utility.

Line to change https://github.com/aws-powertools/powertools-lambda-python/blob/develop/docs/utilities/parameters.md?plain=1#L246

Image

Got a suggestion in mind?

No response

Acknowledgment

  • I understand the final update might be different from my proposed suggestion, or refused.
anafalcao commented

Hello @ConnorKirk ! I agree this is wrongly highlight. I'd say that lines 6, 26, 32 would represent it better. Thanks for opening this!

dcabib commented

Hey @ConnorKir, @anafalcao and @leandrodamascena ! 👋

I took a deep dive into this highlighting issue and can confirm it's a super straightforward fix. Just analyzed the codebase and here's what I found:

The Problem: The current highlighting hl_lines="6 19-25" is focusing on the boto3 session setup (lines 19-25) instead of the actual Powertools magic. It's like highlighting the kitchen prep instead of the main dish! 😅

The Fix: Change hl_lines="6 19-25" to hl_lines="6 26 32" in docs/utilities/parameters.md (around line 246).

This will highlight:

  • Line 6: The Powertools import ✅
  • Line 26: ssm_provider = parameters.SSMProvider(boto3_session=boto3_session) ✅
  • Line 32: all_parameters: Any = ssm_provider.get_multiple("/lambda-powertools/") ✅

Why this makes sense: The current highlighting teaches users about AWS SDK setup, but what they really need to see is how to use the SSMProvider. The new highlighting focuses on the Powertools-specific code that developers actually came to learn about.

Technical details:

  • It's purely a docs change (no build scripts involved)
  • Uses MkDocs with pymdownx.snippets for file inclusion
  • Single line change, zero risk
  • Matches @anafalcao's suggestion perfectly

Ready to help: If you need someone to submit the PR, I'm happy to jump in! This is exactly the kind of developer experience improvement that makes documentation shine. 🚀

anafalcao commented

Hi @dcabib , feel free to open the PR. Thanks!

powertools-for-aws-oss-automation commented

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 reopen the issue, or open a new issue referencing this one.
If you wish to keep having a conversation with other community members under this issue feel free to do so.