aws-doc-sdk-examples icon indicating copy to clipboard operation
aws-doc-sdk-examples copied to clipboard

WRITEME: example is quietly omitted when it has no snippet tags in the first excerpt

Open Laren-AWS opened this issue 1 year ago • 3 comments

When an example has no snippet tags in the first excerpt, it is quietly omitted from the README.

For example, in this Java metadata, the first excerpt is only a description, which is valid. WRITEME detects the example has having no snippets and emits a subtle and rather cryptic warning and quietly omits the example from the output.

    Java:
      versions:
        - sdk_version: 2
          github: javav2/example_code/s3
          sdkguide:
          excerpts:
            - description: Generate a pre-signed URL for an object, then download it (GET request).
            - description: Imports.
              snippet_tags:
                - presigned.java2.generatepresignedgeturlandretrieve.import
            - description: Generate the URL.
              snippet_tags:
                - presigned.java2.generatepresignedgeturlandretrieve.createpresignedurl

Expected

WRITEME digs deeper into the excerpts to find a snippet tag so it can include the example.

Laren-AWS avatar Aug 06 '24 17:08 Laren-AWS

Also, Rachel found a variant where snippet tags from the Ailly template accidentally got higher priority, resulting in the "wrong" file path in the README. So it should choose the "best" by some heuristic.

DavidSouther avatar Aug 16 '24 14:08 DavidSouther

@scmacdon points out https://github.com/awsdocs/aws-doc-sdk-examples/blob/420df9a2b8174b7482bbf2cbc100a051decb5e7d/.doc_gen/metadata/cross_metadata.yaml#L49 generates warnings for WRITEME. Whether these should find the "right" file, or WRITME should not care about these examples, is TBD.

DavidSouther avatar Aug 29 '24 14:08 DavidSouther

I agree - Write Me should not care about these old X-SERs (they are still there) and move on to update Read Me based on YAML. S3 works now but SNS does not update Readme.

scmacdon avatar Aug 29 '24 15:08 scmacdon