docs(parameters): extract inline code examples into snippet files#1197
Merged
Conversation
boring-cyborg
Bot
added
the
documentation
powertools-for-aws-oss-automation
Bot
added
the
size/XXL
|
Not all issues are linked correctly. Please link each issue to the PR either manually or using a closing keyword in the format If mentioning more than one issue, separate them with commas: i.e. |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR continues the documentation refactor to replace inline C# code fences with pymdownx.snippets includes, moving the example code into dedicated snippet .cs files for easier reuse and maintenance. It also adds spec/plan documents describing the broader multi-utility extraction effort.
Changes:
- Replaced inline C# code blocks in
docs/utilities/parameters.mdwith snippet includes and added new snippet files underdocs/snippets/parameters/. - Replaced inline C# blocks in
docs/utilities/jmespath-functions.mdwith snippet includes and addeddocs/snippets/jmespath/ExtractingData.cs. - Added new spec and plan markdown files under
specs/to document the extraction approach and rollout.
Reviewed changes
Copilot reviewed 14 out of 14 changed files in this pull request and generated 13 comments.
Show a summary per file
| File | Description |
|---|---|
| specs/SPEC-2026-0001-extract-inline-code-snippets-from-docs.md | Adds a spec document for the multi-page extraction initiative. |
| specs/2026-04-17-extract-inline-code-snippets-from-docs.md | Adds/refines the spec (v2) including constraints and naming guidance. |
| specs/2026-04-17-extract-inline-code-snippets-from-docs-plan.md | Adds an execution plan and traceability matrix for the work. |
| docs/utilities/parameters.md | Replaces 26 inline C# blocks with pymdownx.snippets includes and normalizes language tags to csharp. |
| docs/utilities/jmespath-functions.md | Replaces inline C# blocks with snippet includes. |
| docs/snippets/jmespath/ExtractingData.cs | New snippet file backing jmespath-functions examples. |
| docs/snippets/parameters/SsmProvider.cs | New snippet file for SSM provider examples. |
| docs/snippets/parameters/SecretsProvider.cs | New snippet file for Secrets Manager examples. |
| docs/snippets/parameters/DynamoDbProvider.cs | New snippet file for DynamoDB provider examples. |
| docs/snippets/parameters/AppConfigProvider.cs | New snippet file for AppConfig provider + feature flag examples. |
| docs/snippets/parameters/Caching.cs | New snippet file for caching/max-age examples. |
| docs/snippets/parameters/TransformValues.cs | New snippet file for transformation examples. |
| docs/snippets/parameters/CustomTransformer.cs | New snippet file for custom transformer examples. |
| docs/snippets/parameters/CustomProvider.cs | New snippet file for custom provider examples. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+4
to
+8
| namespace AWS.Lambda.Powertools.Docs.Snippets.Parameters; | ||
|
|
||
| // --8<-- [start:ssm_provider] | ||
| using AWS.Lambda.Powertools.Parameters; | ||
| using AWS.Lambda.Powertools.Parameters.SimpleSystemsManagement; |
Comment on lines
+4
to
+8
| namespace AWS.Lambda.Powertools.Docs.Snippets.Parameters; | ||
|
|
||
| // --8<-- [start:secrets_provider] | ||
| using AWS.Lambda.Powertools.Parameters; | ||
| using AWS.Lambda.Powertools.Parameters.SecretsManager; |
Comment on lines
+4
to
+8
| namespace AWS.Lambda.Powertools.Docs.Snippets.Parameters; | ||
|
|
||
| // --8<-- [start:dynamodb_provider_single] | ||
| using AWS.Lambda.Powertools.Parameters; | ||
| using AWS.Lambda.Powertools.Parameters.DynamoDB; |
| - **Addressed (2026-04-18)**: Strengthened per-utility delivery constraint in three places: (1) Intent section — added explicit paragraph making one-PR-per-utility a hard constraint with rationale, (2) AC-16 — reinforced that each PR is scoped to exactly one utility, (3) Rollout strategy — added "strictly" qualifier and scope clarification. | ||
|
|
||
| ### AMD-002 (2026-04-19) — Reviewer: @reviewer | ||
| - Clarification on "independent PR": I want to have the branch names in this docuemtn for each pr |
Comment on lines
35
to
39
|
|
||
| === "Transform" | ||
| ```csharp hl_lines="1 2" | ||
| var transformer = JsonTransformer.Parse("powertools_json(body).customerId"); | ||
| using var result = transformer.Transform(doc.RootElement); | ||
|
|
||
| Logger.LogInformation(result.RootElement.GetRawText()); // "dd4649e6-2484-4993-acb8-0f9123103394" | ||
| --8<-- "docs/snippets/jmespath/ExtractingData.cs:transform_json" | ||
| ``` |
Comment on lines
+4
to
+8
| namespace AWS.Lambda.Powertools.Docs.Snippets.Parameters; | ||
|
|
||
| // --8<-- [start:app_config_provider] | ||
| using AWS.Lambda.Powertools.Parameters; | ||
| using AWS.Lambda.Powertools.Parameters.AppConfig; |
Comment on lines
+4
to
+8
| namespace AWS.Lambda.Powertools.Docs.Snippets.Parameters; | ||
|
|
||
| // --8<-- [start:default_max_age] | ||
| using AWS.Lambda.Powertools.Parameters; | ||
| using AWS.Lambda.Powertools.Parameters.SimpleSystemsManagement; |
Comment on lines
+4
to
+8
| namespace AWS.Lambda.Powertools.Docs.Snippets.Parameters; | ||
|
|
||
| // --8<-- [start:json_transformation] | ||
| using AWS.Lambda.Powertools.Parameters; | ||
| using AWS.Lambda.Powertools.Parameters.SimpleSystemsManagement; |
Comment on lines
+13
to
+17
| approvedBy: Henrique Graca | ||
| - docs/core/logging.md | ||
| - docs/core/metrics.md | ||
| - docs/core/tracing.md | ||
| - docs/core/event_handler/appsync_events.md |
| ``` | ||
| docs/snippets/ | ||
| metadata/ | ||
| jmespath-functions/ |
Extract 26 inline C# code blocks from docs/utilities/parameters.md into standalone snippet files under docs/snippets/parameters/ using pymdownx.snippets includes. Normalize language tags from c# to csharp. No visual changes to rendered documentation. Closes #1188
hjgraca
force-pushed
the
docs/extract-parameters-snippets
branch
from
f7c307e to
8d081d2
Compare
powertools-for-aws-oss-automation
Bot
added
size/XXL
|
leandrodamascena
approved these changes
Apr 28, 2026
Contributor
leandrodamascena
left a comment
leandrodamascena
left a comment
There was a problem hiding this comment.
Looks good, thanks!
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Issue number: #1188
Summary
Changes
User experience
No visual changes to rendered documentation. This is a maintainability refactor — code examples are now in standalone .cs files instead of inline in markdown.
Pattern established by #1104 (batch processing + idempotency). Parent tracking issue: #794.
Checklist
Is this a breaking change?
RFC issue number:
Checklist:
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.
Fixes #1188