Docs: extract Metrics code snippets in separate files

[dreamorosi]

What were you searching in the docs?

Currently the code snippets in the documentation under the Metrics's section are hardcoded as part of the page's markdown.

This authoring experience, which doesn't provide linting, is error prone, which causes issues in the docs and in turns to users.

This issue is part of a larger effort being tracked at #729.

Is this related to an existing documentation section?

https://awslabs.github.io/aws-lambda-powertools-typescript/latest/core/metrics/

How can we improve?

The code snippets should be extracted to their own separate files, placed under docs/snippets/metrics.

So for instance, the first snippet that currently reads:

import { Metrics } from '@aws-lambda-powertools/metrics';

const metrics = new Metrics({ namespace: 'serverlessAirline', serviceName: 'orders' });

export const handler = async (_event, _context): Promise<void> => {
    // ...
};

would be replaced with:

--8<-- "docs/snippets/metrics/basicUsage.ts"

And the content should be placed in its own file at the path: docs/snippets/metrics/basicUsage.ts.

This applies to all TypeScript code snippets of the page.

Got a suggestion in mind?

No response

Acknowledgment

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

[dreamorosi]

Names for the files (in order of appearance in this file), if I have forgotten any of them let me know:

1. basicUsage.ts
2. sam.ts
3. createMetrics.ts
4. customDimensions.ts
5. multiValueMetrics.ts
6. defaultDimensions.ts
7. defaultDimensionsMiddy.ts
8. setDefaultDimensions.ts
9. defaultDimensionsDecorator.ts
10. middy.ts
11. decorator.ts
12. manual.ts
13. throwOnEmptyMetrics.ts
14. captureColdStartMetricMiddy.ts
15. captureColdStartMetricDecorator.ts
16. addMetadata.ts
17. singleMetricDifferentDimsMiddy.ts
18. singleMetricDifferentDimsDecorator.ts

[niko-achilles]

@dreamorosi checked the quantity of code snippets and identified the same number of 18. The names you proposed have the corresponding meaning as described in the metrics-docs.

I can start today evening with this issue .

[github-actions]

⚠️ COMMENT VISIBILITY WARNING ⚠️

Comments on closed issues are hard for our team to see.
If you need more assistance, please either tag a team member or open a new issue that references this one.
If you wish to keep having a conversation with other community members under this issue feel free to do so.