aws-doc-sdk-examples
aws-doc-sdk-examples copied to clipboard
SOS: switch to use GitHub-side snippet extractor
Our current build process extracts snippets as part of our internal doc build. We currently also use a snippet extractor in dry-run mode to lint snippet tags. This tool can also be used in full mode to extract snippets on the GitHub side.
Advantages:
- The snippet extractor has more features than the doc build tool and is easier to update.
- Extracting snippets on the GitHub side would allow us to verify snippets when a PR is opened.
Risks:
- The existing tool has been in place for several years and is stable.
- What kind of support can we expect for this tool from the author?
Verification:
- Generate snippets from the internal build.
- Generate snippets from the snippet extractor.
- Compare the output to be sure there is nothing unexpected. The outputs should be close to identical.
- Compare extraction times and size of output to ensure this doesn't negatively impact the PR experience or our repo.
Exit criteria:
Flip the GitHub action to extract snippets. Update the doc build to use extracted snippets. Make sure everything builds as expected.
I would like to see some ability to control or normalize indentation. When joining two separate snippets, they might come from drastically different types of code with different indentation expectations. When this happens, it looks unprofessional in the final product.