Docs: Extract code examples into separate files for linting

[michaelbrewer]

Description of the improvement

Summary of the proposal

Code examples should be extracted to allow for validation / linting to help prevent errors.

How, where did you look for information

See

• Papercuts priorization before we consider v2 powertools-lambda-python#1009
• Docs: Move code snippets into dedicated python files add formatting and linting, fixing any outstanding errors powertools-lambda-python#1064

Missing or unclear documentation

Improvement

• Extract examples into the docs/ folder, to allow for mkdocs to automatically pick it up
• Add autoformatter and linting against these examples
• See python pr as an example: fix(docs): extract code snippets into dedicated python files and fix examples powertools-lambda-python#1065

Related existing documentation

Related issues, RFCs

Example of documentation examples with errors in them:

• docs(all): Fix docs and examples #472

[dreamorosi]

Hi Michael, first off thanks for opening an issue to discuss the proposal.

I think this idea is valuable, I got bitten by this a few times already and having the same linting rules applied to the code snippets would help.

I have a few questions though, mainly coming from my limited knowledge of MKDocs:

1. If we separate the files can we still see them in context when authoring the docs locally?
2. Would each code snippet have its own file?
3. Would it be possible to use the same exact linting rules that we use for the rest of the project?
4. When would this linting step run?

If the answer to number 2 is yes, then if we move forward with the idea, I'd prefer to have a separate PR for each utility: i.e. one PR that addresses all the examples in docs/core/metrics, another for docs/core/logger, etc.
This way we can keep the PR size small and relatively easy to review.

I've marked this as low priority because at the moment we are focusing on the other issues marked as high before we get to GA.

With that said, after the points above have been discussed and agreed upon I'm open to review a PR from the community.

[michaelbrewer]

Hi Michael, first off thanks for opening an issue to discuss the proposal.

I think this idea is valuable, I got bitten by this a few times already and having the same linting rules applied to the code snippets would help.

I have a few questions though, mainly coming from my limited knowledge of MKDocs:

1. If we separate the files can we still see them in context when authoring the docs locally?
2. Would each code snippet have its own file?
3. Would it be possible to use the same exact linting rules that we use for the rest of the project?
4. When would this linting step run?

If the answer to number 2 is yes, then if we move forward with the idea, I'd prefer to have a separate PR for each utility: i.e. one PR that addresses all the examples in docs/core/metrics, another for docs/core/logger, etc. This way we can keep the PR size small and relatively easy to review.

I've marked this as low priority because at the moment we are focusing on the other issues marked as high before we get to GA.

With that said, after the points above have been discussed and agreed upon I'm open to review a PR from the community.

It would be option 2, each example would have it’s own file. You might have shared examples, but a PR per page makes sense.

[michaelbrewer]

@dreamorosi example PR is up #730

[dreamorosi]

Thanks for the PR, but I still would like to clear all the other points before start to review:

With that said, after the points above have been discussed and agreed upon I'm open to review a PR from the community.

Specifically I'd like to understand how/when we are going to actually lint these files.

At the moment I don't have yet a clear picture aside from just splitting the files and if there's no linting then having multiple files just makes it harder to maintain.

[michaelbrewer]

Linting would be hard if you are doing something too strict (like unused variables), but at least it should handle syntax errors, missing parameters etc..

[michaelbrewer]

@dreamorosi so far, i have already found a couple issues like the indents and the same yaml not being valid.

One option could be to configure a more lenient tsconfig to focus on compile errors. However you might still run into errors like:

[dreamorosi]

Thanks for looking into it. I'd like to hear the opinion of the other maintainers as well since it seems that there's no clear-cut way and I'm not clear on whether the overhead of having many more files is worth the gain.

Finally as I have mentioned in my first comment, this is a low priority ticket so please expect some delays in the responses.

[michaelbrewer]

Sure, i get the delay, maybe discuss with the maintainers:
What is the objectives of the code examples? Should they be runnable or only valid syntax?
It is easier to open and edit an example in VSCode with a .ts extension or just inline edit within the .md files?

The part that is frustrating to me is when an example does not have a valid syntax, or in the case of YAML not linted and has invalid indents.

[saragerion]

Thanks for opening this issue @michaelbrewer. This is an improvement that can potentially make sure our docs have better linted examples (which is a very good thing!).

The team is currently busy with other units of work with higher priority for the short term (GA), and we'll discuss about this and get back to you once we have the padding.

[michaelbrewer]

Sure thing already run a couple more issues in the docs.

So i can either file issues for them or keep it fixed in the 1 PR #730

Bugs so far for Tracer docs:

• fix indents to match the projects code style of 2 spaces (minor)
• fix the sam template.yml example, by adding missing fields (handler, AWSTemplateFormatVersion etc.)
• fix missing import for Context tracing https requests example