Clean up READMEs and correct template paths (#46)

README.md

@@ -1,4 +1,6 @@
 # Smithy Examples
+[![Build Status](https://github.com/smithy-lang/smithy-examples/workflows/integ/badge.svg)](https://github.com/smithy-lang/smithy-examples/actions/workflows/integ.yml)
+
 This repository contains a range of examples to help you get up and running with [Smithy](https://smithy.io).
 
 *Note*: You will need the [Smithy CLI](https://smithy.io/2.0/guides/smithy-cli/index.html) installed to use the examples in this
@@ -13,13 +15,13 @@ API documentation, test automation, and example code.
 
 
 ## Examples
-- [Getting Started](getting-started-examples/README.md) - Build the Smithy [quick start example](https://smithy.io/2.0/quickstart.html).
-- [Conversion](conversion-examples/README.md) - Convert Smithy models to other formats (such as OpenAPI) and vice versa 
-- [Custom Traits](custom-trait-examples/README.md) - Create custom Smithy [traits](https://smithy.io/2.0/spec/model.html#traits) to use for defining custom model metadata.
-- [Projections](projection-examples/README.md) - Using Smithy [projections](https://smithy.io/2.0/guides/building-models/build-config.html#projections) to create different views of 
+- [Quick Start](quickstart-examples) - Build the Smithy [quick start example](https://smithy.io/2.0/quickstart.html).
+- [Conversion](conversion-examples) - Convert Smithy models to other formats (such as OpenAPI) and vice versa 
+- [Custom Traits](custom-trait-examples) - Create custom Smithy [traits](https://smithy.io/2.0/spec/model.html#traits) to use for defining custom model metadata.
+- [Projections](projection-examples) - Using Smithy [projections](https://smithy.io/2.0/guides/building-models/build-config.html#projections) to create different views of 
   your model for specific consumers.
-- [Shared Models](shared-models/README.md) - Create a package of common Smithy shapes that can be shared between Smithy models.
-- [Linting and Validation](linting-and-validation-examples/README.md) - Use linters and validators to ensure APIs adhere to best practices and standards.
+- [Shared Models](shared-model-examples) - Create a package of common Smithy shapes that can be shared between Smithy models.
+- [Linting and Validation](linting-and-validation-examples) - Use linters and validators to ensure APIs adhere to best practices and standards.
 
 ## Contributing
 Contributions are welcome. Please read the [contribution guidelines](CONTRIBUTING.md) first.

getting-started-examples/Makefile

@@ -1,32 +0,0 @@
-
-referenceModel = integ/expected-model.json
-cliModelPath = getting-started-cli/build/smithy/source/model/model.json
-gradleModelPath = getting-started-gradle/build/smithyprojections/getting-started-gradle/source/model/model.json
-
-clean:
-	@echo Cleaning build Directories...
-	rm -rf getting-started-cli/build
-	cd getting-started-gradle; ./gradlew clean
-	@echo Cleaning Complete.
-
-cli-example: clean
-	@echo Building getting-started-cli example...
-	cd getting-started-cli; smithy build
-	@echo getting-started-cli example built successfully
-
-test-cli: cli-example
-	@echo Comparing cli build to reference...
-	diff -b $(referenceModel) $(cliModelPath)
-	@echo Cli model matches reference
-
-gradle-example: clean
-	@echo Building getting-started-gradle example...
-	cd getting-started-gradle; ./gradlew build
-	@echo getting-started-gradle example built successfully
-
-test-gradle: gradle-example
-	@echo Comparing gradle build to reference...
-	diff -b $(referenceModel) $(gradleModelPath)
-	@echo Gradle model matches reference
-
-test-all: test-cli test-gradle

linting-and-validation-examples/README.md

@@ -45,11 +45,19 @@ discover the custom linter implementation. See the [custom linter](#custom-linte
 
 For more information on model validation see: [Model Validation](https://smithy.io/2.0/spec/model-validation.html#validation).
 
+### Validation Decorators
+Validation events can be sometimes confusing for newcomers to Smithy and resolving validation events can sometimes require additional
+guidance. Validation decorators allow Smithy users to attach additional hints to Validation events to provide such guidance.
+
+For example, a validation decorator can be used to add the helpful HINT shown below to a validation event:
+
+![alt text](decorators/decorator-hint.png)
 
 ## Examples
 - [Common Linting Configuration](#common-linting-configuration)
 - [Custom Validator](#custom-validator)
-- [Custom Linter ](#custom-linter)
+- [Custom Linter](#custom-linter)
+- [Validation Event Decorators](#decorators)
 
 ---
 ## Common Linting Configuration
@@ -123,3 +131,59 @@ To use this example as a template run the following command.
 ```
 smithy init -t custom-linter
 ```
+
+## Decorators
+This example demonstrates how to create a custom validation decorator package for Smithy.
+
+A custom validation decorator package can be created and added as a dependency to your build system or model package.
+For instance, the Smithy Gradle plugin can be wrapped in an internal package that also has a dependency on your
+decorator package. This way all the users of the internal package will also depend on the decorators package
+without them also having to know about it.
+
+### Custom Validation Decorators
+A custom validation decorator class must implement the
+[`software.amazon.smithy.model.validation.ValidationEventDecorator`](https://smithy.io/javadoc/1.32.0/software/amazon/smithy/model/validation/ValidationEventDecorator.html)
+interface. This class just consists of two methods:
+
+```java
+/** Returns true if this decorator knows how to decorate this event, usually by looking at the event id. */
+boolean canDecorate(ValidationEvent ev)
+
+/** Takes an event and potentially updates it to decorate it. */
+ValidationEvent decorate(ValidationEvent ev)
+```
+
+The `canDecorate` method serves as a quick filter for the decorator to let Smithy know whether it knows how to
+decorate the given event. This usually can be done by using the id of the event which defaults to the name of
+the validator.
+
+The `decorate` method adds additional information to the the validation event by updating the event object but might decide not to and return it
+as-is. Implementations can decide how exactly to update the event but the best way is to add a "hint" to
+nudge the user towards the right solution for the problem.
+
+
+### Decorator Discovery 
+Smithy uses the Java
+[Service Provider Interfaces](https://docs.oracle.com/javase/tutorial/sound/SPI-intro.html) (SPI) to discover
+all the packages offering the validation decorator service and passes each of the validation events through the provided decorators.
+
+In order for the package to expose the validation event decorator service interfaces it provides it MUST include a
+`META-INF/services/software.amazon.smithy.model.validation.ValidationEventDecorator` file inside the jar,
+usually packaged by the build system when found in the `src/main/resources` directory. The file contains the
+fully qualified names of the classes that implement the interface. For this example it contains:
+
+```
+io.smithy.examples.decorators.DecorateUnresolvedShapeEvent
+io.smithy.examples.decorators.DecorateUnresolvedTraitEvent
+```
+
+For the two decorators implemented in this package, `DecorateUnresolvedShapeEvent` and
+`DecorateUnresolvedTraitEvent`.
+
+
+### Use as a template
+To use this example as a template run the following.
+
+```console
+smithy init -t decorators
+```

linting-and-validation-examples/decorators/README.md

@@ -1,58 +1,5 @@
-# Custom Validation Decorators
-
-The examples in this directory demonstrate how to create a custom validation decorator package for Smithy.
-
-Validation events can be sometimes confusing for newcomers to Smithy, and adding some guidance on how to solve
-Validation decorators allow Smithy users to attach additional hints to Validation events to provide such guidance. 
-
-### Custom Validation Decorators Package
-
-A custom validation decorator package can be created and added as a dependency to your build system or model package.
-For instance, the Smithy Gradle plugin can be wrapped in an internal package that also has a dependency on your
-decorator package. This way all the users of the internal package will also depend on the decorators package
-without them also having to know about it.
-
-Smithy uses the Java
-[Service Provider Interfaces](https://docs.oracle.com/javase/tutorial/sound/SPI-intro.html) (SPI) to discover
-all the packages offering this service and pass each of the validation events through the provided decorators 
-generated.
-
-In order for the package to expose the service interfaces it provides it MUST include a
-`META-INF/services/software.amazon.smithy.model.validation.ValidationEventDecorator` file inside the jar,
-usually packaged by the build system when found in the `src/main/resources` directory. The file contains the
-fully qualified names of the classes that implement the interface. For this example it contains:
-
-```
-io.smithy.examples.decorators.DecorateUnresolvedShapeEvent
-io.smithy.examples.decorators.DecorateUnresolvedTraitEvent
-```
-
-For the two decorators implemented in this package, `DecorateUnresolvedShapeEvent` and
-`DecorateUnresolvedTraitEvent`.
-
-### Custom Validation Decorators Class
-
-A custom validation decorator class must implement the
-[`software.amazon.smithy.model.validation.ValidationEventDecorator`](https://smithy.io/javadoc/1.32.0/software/amazon/smithy/model/validation/ValidationEventDecorator.html)
-interface. This class just consists of two methods:
-
-```java
-/** Returns true if this decorator knows how to decorate this event, usually by looking at the event id. */
-boolean canDecorate(ValidationEvent ev)
-
-/** Takes an event and potentially updates it to decorate it. */
-ValidationEvent decorate(ValidationEvent ev)
-```
-
-The `canDecorate` method serves as a quick filter for the decorator to let Smithy know whether it knows how to
-decorate the given event. This usually can be done by using the id of the event which defaults to the name of
-the validator.
-
-The `decorate` method adds additional information to the the validation event by updating the event object but might decide not to and return it
-as-is. Implementations can decide how exactly to update the event but the best way is to add a "hint" to
-nudge the user towards the right solution for the problem.
-
-### Example for Gradle
+# Custom Validation Decorators Package
+Use this example to create a custom validation decorator package for Smithy.
 
 The example contained in this package assumes that the user is using [`Gradle`](https://gradle.org/) as a
 build system and Kotlin for the configuration `build.gradle.kts`, when a validation event for an unresolved
@@ -65,6 +12,8 @@ You might be missing a dependency to the package `smithy-validation-model`. Try
 
 And Smithy will add nice formatting to the output. Something similar to the image below.
 
+![alt text](decorator-hint.png)
+
 ## Building
 To build this package run the following from the root of the package:
 
@@ -75,16 +24,3 @@ To build this package run the following from the root of the package:
 This will generate a `build` directory containing the build artifacts generated by
 gradle. The generated JAR file that should be used by downstream consumers can be
 found at `build/libs/decorators.jar`
-
-
-![alt text](decorator-hint.png)
-
-
-### Use as a template
-To use this example as a template run the following.
-
-```console
-smithy init -t decorators
-```
-
----

quickstart-examples/Makefile

@@ -0,0 +1,32 @@
+
+referenceModel = integ/expected-model.json
+cliModelPath = quickstart-cli/build/smithy/source/model/model.json
+gradleModelPath = quickstart-gradle/build/smithyprojections/quickstart-gradle/source/model/model.json
+
+clean:
+	@echo Cleaning build Directories...
+	rm -rf quickstart-cli/build
+	cd quickstart-gradle; ./gradlew clean
+	@echo Cleaning Complete.
+
+cli-example: clean
+	@echo Building quickstart-cli example...
+	cd quickstart-cli; smithy build
+	@echo quickstart-cli example built successfully
+
+test-cli: cli-example
+	@echo Comparing cli build to reference...
+	diff -b $(referenceModel) $(cliModelPath)
+	@echo Cli model matches reference
+
+gradle-example: clean
+	@echo Building quickstart-gradle example...
+	cd quickstart-gradle; ./gradlew build
+	@echo quickstart-gradle example built successfully
+
+test-gradle: gradle-example
+	@echo Comparing gradle build to reference...
+	diff -b $(referenceModel) $(gradleModelPath)
+	@echo Gradle model matches reference
+
+test-all: test-cli test-gradle

quickstart-examples/README.md

@@ -1,4 +1,4 @@
-# Getting started Example
+# Quick Start Example
 This directory provides examples of building complete Smithy model for 
 the Weather Service from the [Smithy Quick Start Guide](https://smithy.io/2.0/quickstart.html) 
 using a number of different build systems.
@@ -14,17 +14,17 @@ This example uses the [smithy cli](https://smithy.io/2.0/guides/smithy-cli/index
 ### Usage
 You can use this example in your local workspace by executing the following command:
 ```console
-smithy init
+smithy init -t quickstart-cli
 ```
-Then, build the example by executing `smithy build` in the newly created `getting-started`
+Then, build the example by executing `smithy build` in the newly created `quickstart-cli`
 directory.
 
 
 ## Gradle
-This examples use the [smithy-gradle-plugin](https://github.com/awslabs/smithy-gradle-plugin) to build the Weather Service model.
+This example uses the [smithy-gradle-plugin](https://github.com/awslabs/smithy-gradle-plugin) to build the Weather Service model.
 
 ```console
-smithy init -t getting-started-gradle
+smithy init -t quickstart-gradle
 ```
 
-To build the Weather Service model run `./gradlew clean build` from the newly created `getting-started-gradle` directory.
+To build the Weather Service model run `./gradlew clean build` from the newly created `quickstart-gradle` directory.

quickstart-examples/quickstart-gradle/settings.gradle.kts

@@ -7,4 +7,4 @@ pluginManagement {
     }
 }
 
-rootProject.name = "getting-started-gradle"
+rootProject.name = "quickstart-gradle"

settings.gradle.kts

@@ -22,7 +22,7 @@ include(":custom-trait-examples:integ:custom-structure-trait-test")
 
 // ---- shared models ----
 // Template directories
-include(":shared-model-examples:common")
+include(":shared-model-examples:common-shapes")
 
 // Integration Tests
 include(":shared-model-examples:integ")

shared-model-examples/README.md

@@ -16,6 +16,6 @@ downstream consumers of the `common-shapes` package.
 To use this example as a template run the following.
 
 ```
-smithy init -t shared-shapes
+smithy init -t shared-model-package
 ```
 

shared-model-examples/common-shapes/settings.gradle.kts

@@ -1,5 +1,5 @@
 
-rootProject.name = "common"
+rootProject.name = "common-shapes"
 
 pluginManagement {
     repositories {

shared-model-examples/integ/build.gradle.kts

@@ -25,5 +25,5 @@ buildscript {
 dependencies {
     val smithyVersion: String by project
 
-    implementation(project(":shared-model-examples:common"))
+    implementation(project(":shared-model-examples:common-shapes"))
 }

smithy-templates.json

@@ -2,12 +2,12 @@
   "name": "smithy-examples",
   "templates": {
     "quickstart-cli": {
-      "documentation": "Smithy Quickstart example weather service using the Smithy CLI.",
-      "path": "getting-started-examples/getting-started-cli"
+      "documentation": "Smithy Quick Start example weather service using the Smithy CLI.",
+      "path": "quickstart-examples/quickstart-cli"
     },
     "quickstart-gradle": {
-      "documentation": "Smithy Quickstart example weather service using the Smithy-Gradle-Plugin.",
-      "path": "getting-started-examples/getting-started-gradle",
+      "documentation": "Smithy Quick Start example weather service using the Smithy-Gradle-Plugin.",
+      "path": "quickstart-examples/quickstart-gradle",
       "include": [ ".gitignore", ".gitattributes" ]
     },
     "custom-annotation-trait": {
@@ -59,7 +59,7 @@
     },
     "shared-model-package": {
       "documentation": "Gradle project to create a shared package of common Smithy models.",
-      "path": "shared-model-examples/common",
+      "path": "shared-model-examples/common-shapes",
       "include": [
         "config/",
         "gradle/",