Skip to content

Commit fe0e0db

Browse files
hjgracahjgraca
committed
spec: approve 2026-04-17-extract-inline-code-snippets-from-docs-plan
1 parent 5f1efd4 commit fe0e0db

1 file changed

Lines changed: 347 additions & 0 deletions

File tree

‎specs/2026-04-17-extract-inline-code-snippets-from-docs-plan.md‎

Lines changed: 347 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,347 @@
1+
---
2+
id: 2026-04-17-extract-inline-code-snippets-from-docs-plan
3+
spec: 2026-04-17-extract-inline-code-snippets-from-docs
4+
title: "Plan: Extract inline C# code examples from documentation into standalone snippet files"
5+
type: plan
6+
status: approved
7+
tier: light
8+
version: 1
9+
created: 2026-04-19
10+
author: architect-agent + henrigra
11+
reviewedBy:
12+
approvedBy: Henrique Graca
13+
branch: specforge/2026-04-17-extract-inline-code-snippets-from-docs
14+
---
15+
16+
# Plan: Extract inline C# code examples from documentation into standalone snippet files
17+
18+
**Spec:** 2026-04-17-extract-inline-code-snippets-from-docs (v2)
19+
**Tier:** light (checkpoints 3 and 5 only)
20+
**Estimated tasks:** 10
21+
22+
## Traceability Matrix
23+
24+
| AC | Description | Verification | Tasks |
25+
|---|---|---|---|
26+
| AC-1 | All inline C# blocks extracted to `.cs` files | [structural] | T1–T9 |
27+
| AC-2 | Two-line comment header on each `.cs` file | [structural] | T1–T9 |
28+
| AC-3 | Namespace `AWS.Lambda.Powertools.Docs.Snippets.<Utility>` | [structural] | T1–T9 |
29+
| AC-4 | Named subsections with `--8<--` start/end markers | [structural] | T1–T9 |
30+
| AC-5 | Markdown uses `--8<--` snippet includes | [structural] | T1–T9 |
31+
| AC-6 | PascalCase snippet file names | [structural] | T1–T9 |
32+
| AC-7 | Logical grouping of snippet files by doc section | [human] | T1–T9 |
33+
| AC-8 | Language tags normalized to `csharp` | [auto] | T1–T9 |
34+
| AC-9 | `hl_lines` recalculated mechanically | [human] | T1–T9 |
35+
| AC-10 | Code annotations preserved in `.cs` files | [structural] | T1–T9 |
36+
| AC-11 | Non-C# blocks stay inline | [structural] | T1–T9 |
37+
| AC-12 | Tabbed content structure preserved | [human] | T1–T9 |
38+
| AC-13 | Prose untouched | [human] | T1–T9 |
39+
| AC-14 | `mkdocs build --strict` succeeds | [auto] | T1–T9 |
40+
| AC-15 | Visually identical rendering | [human] | T1–T9 |
41+
| AC-16 | Scoped to single utility per PR | [structural] | T1–T9 |
42+
| AC-17 | No changes to `mkdocs.yml` | [auto] | T1–T9 |
43+
| AC-18 | PR targets `develop` branch | [auto] | T1–T9 |
44+
| AC-19 | PR title follows `docs(<utility>): extract inline code examples into snippet files` | [structural] | T1–T9 |
45+
| AC-20 | PR references #794, links #1104, linked to sub-issue | [human] | T0, T1–T9 |
46+
47+
## File Map
48+
49+
### New files
50+
51+
**Snippet directories and `.cs` files (one directory per task T1–T9):**
52+
53+
| Directory | Snippet Files |
54+
|---|---|
55+
| `docs/snippets/metadata/` | `GettingStarted.cs`, `UseCases.cs` |
56+
| `docs/snippets/jmespath/` | `ExtractingData.cs` |
57+
| `docs/snippets/tracing/` | `GettingStarted.cs`, `AnnotationsAndMetadata.cs`, `UsingStatementPattern.cs`, `CallbackPattern.cs`, `SubsegmentMethods.cs`, `SdkInstrumentation.cs`, `AotSupport.cs` |
58+
| `docs/snippets/appsync-events/` | `GettingStarted.cs`, `WildcardPatterns.cs`, `AggregatedProcessing.cs`, `ErrorHandling.cs`, `AdvancedUsage.cs`, `Testing.cs` |
59+
| `docs/snippets/bedrock-agent-function/` | `GettingStarted.cs`, `ResponseFormat.cs`, `AdvancedUsage.cs`, `DependencyInjection.cs`, `CompleteExample.cs` |
60+
| `docs/snippets/metrics/` | `GettingStarted.cs`, `CreatingMetrics.cs`, `DefaultDimensions.cs`, `AddingDimensions.cs`, `FlushingMetrics.cs`, `CaptureColdStart.cs`, `AdvancedConfiguration.cs`, `AspNetCore.cs`, `Testing.cs` |
61+
| `docs/snippets/parameters/` | `SsmProvider.cs`, `SecretsProvider.cs`, `DynamoDbProvider.cs`, `AppConfigProvider.cs`, `Caching.cs`, `TransformValues.cs`, `CustomTransformer.cs`, `CustomProvider.cs` |
62+
| `docs/snippets/kafka/` | `GettingStarted.cs`, `ProcessingEvents.cs`, `DeserializingKeysValues.cs`, `PrimitiveTypes.cs`, `AdvancedUsage.cs`, `Testing.cs` |
63+
| `docs/snippets/logging/` | `GettingStarted.cs`, `Configuration.cs`, `MessageTemplates.cs`, `LoggingEvent.cs`, `CorrelationId.cs`, `AppendingKeys.cs`, `ExtraKeys.cs`, `ClearState.cs`, `SamplingDebugLogs.cs`, `OutputCasing.cs`, `AdvancedConfiguration.cs`, `CustomLogFormatter.cs`, `LogBuffering.cs`, `TimestampFormatting.cs`, `AotSupport.cs`, `Testing.cs` |
64+
65+
### Modified files
66+
67+
| File | Changes |
68+
|---|---|
69+
| `docs/utilities/metadata.md` | Replace 5 inline C# blocks with snippet includes |
70+
| `docs/utilities/jmespath-functions.md` | Replace 4 inline C# blocks with snippet includes |
71+
| `docs/core/tracing.md` | Replace 16 inline C# blocks with snippet includes, normalize `c#` → `csharp` |
72+
| `docs/core/event_handler/appsync_events.md` | Replace 13 inline C# blocks with snippet includes, fix `chsarp` typo |
73+
| `docs/core/event_handler/bedrock_agent_function.md` | Replace 14 inline C# blocks with snippet includes |
74+
| `docs/core/metrics.md` | Replace 30 inline C# blocks with snippet includes, fix `python` mislabel |
75+
| `docs/utilities/parameters.md` | Replace 26 inline C# blocks with snippet includes, normalize `c#` → `csharp` |
76+
| `docs/utilities/kafka.md` | Replace 14 inline C# blocks with snippet includes, normalize `c#` → `csharp` |
77+
| `docs/core/logging.md` | Replace 40 inline C# blocks with snippet includes, normalize `c#`/`cs` → `csharp` |
78+
79+
---
80+
81+
## Tasks
82+
83+
### T0: Create sub-issues under #794
84+
85+
**Checkpoint:** 5
86+
**ACs:** [AC-20]
87+
88+
**Steps:**
89+
90+
1. Create 9 GitHub sub-issues under parent issue #794, one per utility:
91+
- `docs(metadata): extract inline code examples into snippet files`
92+
- `docs(jmespath-functions): extract inline code examples into snippet files`
93+
- `docs(tracing): extract inline code examples into snippet files`
94+
- `docs(appsync-events): extract inline code examples into snippet files`
95+
- `docs(bedrock-agent-function): extract inline code examples into snippet files`
96+
- `docs(metrics): extract inline code examples into snippet files`
97+
- `docs(parameters): extract inline code examples into snippet files`
98+
- `docs(kafka): extract inline code examples into snippet files`
99+
- `docs(logging): extract inline code examples into snippet files`
100+
2. Each sub-issue body references parent #794, links PR #1104 as precedent, and includes the relevant row from the spec's complexity table
101+
3. Label each sub-issue with `documentation`
102+
103+
**Verify:**
104+
- `gh issue list --repo aws-powertools/powertools-lambda-dotnet --search "extract inline code" --label documentation --json number,title | jq length` returns 9 (AC-20)
105+
106+
---
107+
108+
### T1: Extract metadata snippets
109+
110+
**Checkpoint:** 3
111+
**ACs:** [AC-1 through AC-19]
112+
**Branch:** `docs/extract-metadata-snippets`
113+
**Files:**
114+
- Create: `docs/snippets/metadata/GettingStarted.cs`, `docs/snippets/metadata/UseCases.cs`
115+
- Modify: `docs/utilities/metadata.md`
116+
117+
**Steps:**
118+
119+
1. `git checkout -b docs/extract-metadata-snippets develop`
120+
2. Create `docs/snippets/metadata/` directory
121+
3. Create `GettingStarted.cs` with:
122+
- Two-line comment header referencing `docs/utilities/metadata.md`
123+
- Namespace `AWS.Lambda.Powertools.Docs.Snippets.Metadata`
124+
- Sections: `getting_started`, `error_handling`, `refresh_metadata`
125+
4. Create `UseCases.cs` with:
126+
- Same header and namespace
127+
- Sections: `multi_az_routing`, `logging_with_metadata`
128+
5. Update `metadata.md`: replace each inline C# block with `--8<-- "docs/snippets/metadata/..."` include, normalize language tags to `csharp`
129+
6. No `hl_lines` recalculation needed (0 blocks have `hl_lines`)
130+
131+
**Verify:**
132+
- `grep -cE '^\`\`\`(c#|cs|C#|chsarp)' docs/utilities/metadata.md` returns 0 (AC-8)
133+
- `mkdocs build --strict` succeeds (AC-14)
134+
- `git diff --name-only develop` shows only `docs/utilities/metadata.md` and `docs/snippets/metadata/*` (AC-16, AC-17)
135+
- Visual inspection in `make docs-local-docker` (AC-15)
136+
137+
---
138+
139+
### T2: Extract jmespath-functions snippets
140+
141+
**Checkpoint:** 3
142+
**ACs:** [AC-1 through AC-19]
143+
**Branch:** `docs/extract-jmespath-functions-snippets`
144+
**Files:**
145+
- Create: `docs/snippets/jmespath/ExtractingData.cs`
146+
- Modify: `docs/utilities/jmespath-functions.md`
147+
148+
**Steps:**
149+
150+
1. `git checkout -b docs/extract-jmespath-functions-snippets develop`
151+
2. Create `docs/snippets/jmespath/` directory
152+
3. Create `ExtractingData.cs` with:
153+
- Two-line comment header referencing `docs/utilities/jmespath-functions.md`
154+
- Namespace `AWS.Lambda.Powertools.Docs.Snippets.JmespathFunctions`
155+
- Sections: `transform_json`, `idempotency_event_key_jmespath`, `powertools_base64`, `powertools_base64_gzip`
156+
4. Update `jmespath-functions.md`: replace 4 inline C# blocks with snippet includes, normalize language tags to `csharp`
157+
5. Recalculate `hl_lines` for 2 blocks that have them
158+
159+
**Verify:**
160+
- `grep -cE '^\`\`\`(c#|cs|C#|chsarp)' docs/utilities/jmespath-functions.md` returns 0 (AC-8)
161+
- `mkdocs build --strict` succeeds (AC-14)
162+
- `git diff --name-only develop` shows only `docs/utilities/jmespath-functions.md` and `docs/snippets/jmespath/*` (AC-16, AC-17)
163+
- Visual inspection in `make docs-local-docker` (AC-15)
164+
165+
---
166+
167+
### T3: Extract tracing snippets
168+
169+
**Checkpoint:** 3
170+
**ACs:** [AC-1 through AC-19]
171+
**Branch:** `docs/extract-tracing-snippets`
172+
**Files:**
173+
- Create: `docs/snippets/tracing/GettingStarted.cs`, `AnnotationsAndMetadata.cs`, `UsingStatementPattern.cs`, `CallbackPattern.cs`, `SubsegmentMethods.cs`, `SdkInstrumentation.cs`, `AotSupport.cs`
174+
- Modify: `docs/core/tracing.md`
175+
176+
**Steps:**
177+
178+
1. `git checkout -b docs/extract-tracing-snippets develop`
179+
2. Create `docs/snippets/tracing/` directory
180+
3. Create 7 `.cs` files with header, namespace `AWS.Lambda.Powertools.Docs.Snippets.Tracing`, and named subsections as detailed in the file map
181+
4. Update `tracing.md`: replace 16 inline C# blocks with snippet includes, normalize all `c#` tags to `csharp`
182+
5. Recalculate `hl_lines` for 15 blocks
183+
184+
**Verify:**
185+
- `grep -cE '^\`\`\`(c#|cs|C#|chsarp)' docs/core/tracing.md` returns 0 (AC-8)
186+
- `mkdocs build --strict` succeeds (AC-14)
187+
- `git diff --name-only develop` shows only `docs/core/tracing.md` and `docs/snippets/tracing/*` (AC-16, AC-17)
188+
- Visual inspection in `make docs-local-docker` (AC-15)
189+
190+
---
191+
192+
### T4: Extract appsync-events snippets
193+
194+
**Checkpoint:** 3
195+
**ACs:** [AC-1 through AC-19]
196+
**Branch:** `docs/extract-appsync-events-snippets`
197+
**Files:**
198+
- Create: `docs/snippets/appsync-events/GettingStarted.cs`, `WildcardPatterns.cs`, `AggregatedProcessing.cs`, `ErrorHandling.cs`, `AdvancedUsage.cs`, `Testing.cs`
199+
- Modify: `docs/core/event_handler/appsync_events.md`
200+
201+
**Steps:**
202+
203+
1. `git checkout -b docs/extract-appsync-events-snippets develop`
204+
2. Create `docs/snippets/appsync-events/` directory
205+
3. Create 6 `.cs` files with header, namespace `AWS.Lambda.Powertools.Docs.Snippets.AppSyncEvents`, and named subsections
206+
4. **Fix `chsarp` typo** at lines 242 and 268 — normalize to `csharp`
207+
5. **Fix Python-style comment** at line 330 — change `#` to `//`
208+
6. Update `appsync_events.md`: replace 13 inline C# blocks with snippet includes
209+
7. Recalculate `hl_lines` for 3 blocks
210+
211+
**Verify:**
212+
- `grep -cE '^\`\`\`(c#|cs|C#|chsarp)' docs/core/event_handler/appsync_events.md` returns 0 (AC-8)
213+
- `mkdocs build --strict` succeeds (AC-14)
214+
- `git diff --name-only develop` shows only `docs/core/event_handler/appsync_events.md` and `docs/snippets/appsync-events/*` (AC-16, AC-17)
215+
- Visual inspection in `make docs-local-docker` (AC-15)
216+
217+
---
218+
219+
### T5: Extract bedrock-agent-function snippets
220+
221+
**Checkpoint:** 3
222+
**ACs:** [AC-1 through AC-19]
223+
**Branch:** `docs/extract-bedrock-agent-function-snippets`
224+
**Files:**
225+
- Create: `docs/snippets/bedrock-agent-function/GettingStarted.cs`, `ResponseFormat.cs`, `AdvancedUsage.cs`, `DependencyInjection.cs`, `CompleteExample.cs`
226+
- Modify: `docs/core/event_handler/bedrock_agent_function.md`
227+
228+
**Steps:**
229+
230+
1. `git checkout -b docs/extract-bedrock-agent-function-snippets develop`
231+
2. Create `docs/snippets/bedrock-agent-function/` directory
232+
3. Create 5 `.cs` files with header, namespace `AWS.Lambda.Powertools.Docs.Snippets.BedrockAgentFunction`, and named subsections
233+
4. Update `bedrock_agent_function.md`: replace 14 inline C# blocks with snippet includes, normalize language tags to `csharp`
234+
5. Recalculate `hl_lines` for 2 blocks
235+
236+
**Verify:**
237+
- `grep -cE '^\`\`\`(c#|cs|C#|chsarp)' docs/core/event_handler/bedrock_agent_function.md` returns 0 (AC-8)
238+
- `mkdocs build --strict` succeeds (AC-14)
239+
- `git diff --name-only develop` shows only `docs/core/event_handler/bedrock_agent_function.md` and `docs/snippets/bedrock-agent-function/*` (AC-16, AC-17)
240+
- Visual inspection in `make docs-local-docker` (AC-15)
241+
242+
---
243+
244+
### T6: Extract metrics snippets
245+
246+
**Checkpoint:** 3
247+
**ACs:** [AC-1 through AC-19]
248+
**Branch:** `docs/extract-metrics-snippets`
249+
**Files:**
250+
- Create: `docs/snippets/metrics/GettingStarted.cs`, `CreatingMetrics.cs`, `DefaultDimensions.cs`, `AddingDimensions.cs`, `FlushingMetrics.cs`, `CaptureColdStart.cs`, `AdvancedConfiguration.cs`, `AspNetCore.cs`, `Testing.cs`
251+
- Modify: `docs/core/metrics.md`
252+
253+
**Steps:**
254+
255+
1. `git checkout -b docs/extract-metrics-snippets develop`
256+
2. Create `docs/snippets/metrics/` directory
257+
3. Create 9 `.cs` files with header, namespace `AWS.Lambda.Powertools.Docs.Snippets.Metrics`, and named subsections
258+
4. **Fix `python` mislabel** at line 444 — change to `csharp`
259+
5. **Preserve `title=` attribute** on the code fence at line 989
260+
6. Update `metrics.md`: replace 30 inline C# blocks with snippet includes, normalize language tags to `csharp`
261+
7. Recalculate `hl_lines` for 22 blocks
262+
263+
**Verify:**
264+
- `grep -cE '^\`\`\`(c#|cs|C#|chsarp|python)' docs/core/metrics.md` returns 0 for C# blocks (AC-8)
265+
- `mkdocs build --strict` succeeds (AC-14)
266+
- `git diff --name-only develop` shows only `docs/core/metrics.md` and `docs/snippets/metrics/*` (AC-16, AC-17)
267+
- Visual inspection in `make docs-local-docker` (AC-15)
268+
269+
---
270+
271+
### T7: Extract parameters snippets
272+
273+
**Checkpoint:** 3
274+
**ACs:** [AC-1 through AC-19]
275+
**Branch:** `docs/extract-parameters-snippets`
276+
**Files:**
277+
- Create: `docs/snippets/parameters/SsmProvider.cs`, `SecretsProvider.cs`, `DynamoDbProvider.cs`, `AppConfigProvider.cs`, `Caching.cs`, `TransformValues.cs`, `CustomTransformer.cs`, `CustomProvider.cs`
278+
- Modify: `docs/utilities/parameters.md`
279+
280+
**Steps:**
281+
282+
1. `git checkout -b docs/extract-parameters-snippets develop`
283+
2. Create `docs/snippets/parameters/` directory
284+
3. Create 8 `.cs` files with header, namespace `AWS.Lambda.Powertools.Docs.Snippets.Parameters`, and named subsections
285+
4. Update `parameters.md`: replace 26 inline C# blocks with snippet includes, normalize all `c#` tags to `csharp`
286+
5. Recalculate `hl_lines` for 22 blocks
287+
6. Be careful not to extract inline code spans (e.g., `` ```BaseProvider``` ``) — these are NOT fenced blocks
288+
289+
**Verify:**
290+
- `grep -cE '^\`\`\`(c#|cs|C#|chsarp)' docs/utilities/parameters.md` returns 0 (AC-8)
291+
- `mkdocs build --strict` succeeds (AC-14)
292+
- `git diff --name-only develop` shows only `docs/utilities/parameters.md` and `docs/snippets/parameters/*` (AC-16, AC-17)
293+
- Visual inspection in `make docs-local-docker` (AC-15)
294+
295+
---
296+
297+
### T8: Extract kafka snippets
298+
299+
**Checkpoint:** 3
300+
**ACs:** [AC-1 through AC-19]
301+
**Branch:** `docs/extract-kafka-snippets`
302+
**Files:**
303+
- Create: `docs/snippets/kafka/GettingStarted.cs`, `ProcessingEvents.cs`, `DeserializingKeysValues.cs`, `PrimitiveTypes.cs`, `AdvancedUsage.cs`, `Testing.cs`
304+
- Modify: `docs/utilities/kafka.md`
305+
306+
**Steps:**
307+
308+
1. `git checkout -b docs/extract-kafka-snippets develop`
309+
2. Create `docs/snippets/kafka/` directory
310+
3. Create 6 `.cs` files with header, namespace `AWS.Lambda.Powertools.Docs.Snippets.Kafka`, and named subsections
311+
4. Update `kafka.md`: replace 14 inline C# blocks with snippet includes, normalize `c#` tags to `csharp`
312+
5. Recalculate `hl_lines` for 9 blocks
313+
314+
**Verify:**
315+
- `grep -cE '^\`\`\`(c#|cs|C#|chsarp)' docs/utilities/kafka.md` returns 0 (AC-8)
316+
- `mkdocs build --strict` succeeds (AC-14)
317+
- `git diff --name-only develop` shows only `docs/utilities/kafka.md` and `docs/snippets/kafka/*` (AC-16, AC-17)
318+
- Visual inspection in `make docs-local-docker` (AC-15)
319+
320+
---
321+
322+
### T9: Extract logging snippets
323+
324+
**Checkpoint:** 3
325+
**ACs:** [AC-1 through AC-19]
326+
**Branch:** `docs/extract-logging-snippets`
327+
**Files:**
328+
- Create: `docs/snippets/logging/GettingStarted.cs`, `Configuration.cs`, `MessageTemplates.cs`, `LoggingEvent.cs`, `CorrelationId.cs`, `AppendingKeys.cs`, `ExtraKeys.cs`, `ClearState.cs`, `SamplingDebugLogs.cs`, `OutputCasing.cs`, `AdvancedConfiguration.cs`, `CustomLogFormatter.cs`, `LogBuffering.cs`, `TimestampFormatting.cs`, `AotSupport.cs`, `Testing.cs`
329+
- Modify: `docs/core/logging.md`
330+
331+
**Steps:**
332+
333+
1. `git checkout -b docs/extract-logging-snippets develop`
334+
2. Create `docs/snippets/logging/` directory
335+
3. Create 16 `.cs` files with header, namespace `AWS.Lambda.Powertools.Docs.Snippets.Logging`, and named subsections
336+
4. **Fix single-quoted strings** in log buffering examples (lines ~1213, 1220, 1225, 1262, 1267, 1293, 1304, 1346) — change `'string'` to `"string"` for valid C#
337+
5. Update `logging.md`: replace 40 inline C# blocks with snippet includes, normalize `c#` and `cs` tags to `csharp`
338+
6. Recalculate `hl_lines` for 27 blocks
339+
7. Handle the unindented tab content at line 171 (code fence at column 0 inside a tab)
340+
341+
**Verify:**
342+
- `grep -cE '^\`\`\`(c#|cs|C#|chsarp)' docs/core/logging.md` returns 0 (AC-8)
343+
- `mkdocs build --strict` succeeds (AC-14)
344+
- `git diff --name-only develop` shows only `docs/core/logging.md` and `docs/snippets/logging/*` (AC-16, AC-17)
345+
- Visual inspection in `make docs-local-docker` (AC-15)
346+
347+
## Amendments

0 commit comments

Comments
 (0)