Skip to content
This repository has been archived by the owner on Jun 15, 2023. It is now read-only.

Adjust snippet clipping in S3 Glacier example #37

Merged
merged 1 commit into from
Dec 28, 2021
Merged

Adjust snippet clipping in S3 Glacier example #37

merged 1 commit into from
Dec 28, 2021

Conversation

camerondurham
Copy link
Contributor

@camerondurham camerondurham commented Sep 6, 2021

Issue #, if available:
No open issues found.

Description of changes:

Dedent the code snippet to avoid clipping in Glacier example:

image

Matching closest file that includes full file as snippet rather than pieces: https://github.com/awsdocs/aws-go-developer-guide/blob/master/doc_source/kms-example-create-key.rst

From briefly looking over all snippets in the doc, I believe this is the only full file snippet with this issue. However, there are other clipping errors such as in this file where the import section is clipped and func is missing on CloudWatch Disable Actions On An Alarm.

I have run python build_docs.py singlehtml but unable to completely verify changes locally since the output looked significantly different than current docs. I opted to make a smaller change that exactly matched similar files. I can file an issue with how the doc build failed if desired but all snippets were all off by ~15 lines after the script successfully ran (with warnings).

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Thanks for considering this change! I'm not sure if this repository or SDK is still active but do plan to test and use this. README seems to suggest this repo is still used.

@camerondurham camerondurham changed the title Dedent glacier snippets Adjust snippet clipping in S3 Glacier example Sep 6, 2021
@Paul-B-AWS Paul-B-AWS merged commit 47fbb9c into awsdocs:master Dec 28, 2021
@Paul-B-AWS
Copy link
Member

@camerondurham, thanks for raising this issue and also for the pointers to other possible anomalies.

@Paul-B-AWS
Copy link
Member

@camerondurham Regarding your comment about the Python build looking significantly different from the web site...
This is a known issue. It stems from metadata that has been added to the code examples that live in the AWS Code Examples Repository.

For example, look at the first 11 lines of create_vault.go.
For the web build, those lines are read and then removed before the code is fed into the build process.
We account for this behavior when calculating the desired line numbers for the content source files.
For example, notice in using-glacier-with-go-sdk.rst (the section for "Create a vault"), we have :lines: 15-.
So for the web build, the code is actually pulled from line (15 + 11 = 26) of the original code example file from the AWS Code Examples Repository.

The local build, on the other hand, doesn't account for the web-build behavior, so starts counting code lines from the beginning of the original code example file.

Hope this explanation helps.

@camerondurham
Copy link
Contributor Author

@Paul-B-AWS Thank you for the really thorough explanation! That complexity of doc-building is new to me and the details will be helpful in case I submit another PR for this.

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants