Include more specific build examples and links

README.md

@@ -58,9 +58,20 @@ plugins {
 }
 ```
 
-Find out more about building artifacts of your Smithy model in the [Building
-Smithy Models][building] guide.
+Finally, create your first model `model/main.smithy`:
+
+```
+namespace com.example
 
+service ExampleService {
+    version: "2020-05-27"
+}
+```
+
+Find out more about building artifacts of your Smithy model in the [Building
+Smithy Models][building] guide. For more examples, see the
+[examples directory](https://github.com/awslabs/smithy-gradle-plugin/tree/master/examples)
+of the Smithy Gradle Plugin repository.
 
 # License
 

docs/source/1.0/guides/building-models/build-config.rst

@@ -29,7 +29,7 @@ The configuration file accepts the following properties:
       - **Required.** Defines the version of SmithyBuild. Set to `1.0`.
     * - outputDirectory
       - ``string``
-      - **Required.** The location where projections are written. Each
+      - The location where projections are written. Each
         projection will create a subdirectory named after the projection, and
         the artifacts from the projection, including a ``model.json`` file,
         will be placed in the directory.
@@ -243,7 +243,7 @@ Applies the transforms defined in the given projection names.
         }
 
 
-.. excludeShapesByTag-transform:
+.. _excludeShapesByTag-transform:
 
 excludeShapesByTag
 ------------------

docs/source/1.0/guides/building-models/gradle-plugin.rst

@@ -349,6 +349,12 @@ The above Smithy plugin also requires a ``buildscript`` dependency in
             }
         }
 
+Complete Examples
+=================
 
+For several complete examples, see the `examples directory`_ of the Smithy
+Gradle plugin repository.
+
+.. _examples directory: https://github.com/awslabs/smithy-gradle-plugin/tree/master/examples
 .. _Smithy Gradle plugin: https://github.com/awslabs/smithy-gradle-plugin/
 .. _Gradle: https://gradle.org/

docs/source/1.0/guides/building-models/index.rst

@@ -1,3 +1,5 @@
+.. _building-models:
+
 ======================
 Building Smithy Models
 ======================

docs/source/1.0/spec/core/shapes.rst

@@ -837,7 +837,7 @@ The following example defines a union shape with several members:
             "smithy": "1.0",
             "shapes": {
                 "smithy.example#MyUnion": {
-                    "type": "structure",
+                    "type": "union",
                     "members": {
                         "i32": {
                             "target": "smithy.api#Integer"

docs/source/quickstart.rst

@@ -681,6 +681,49 @@ service.
             }
         }
 
+Building the Model
+==================
+
+Now that you have a model, you'll want to build it and generate things from it.
+Building the model creates projections of the model, applies plugins to
+generate artifacts, runs validation, and creates a JAR that contains the
+filtered projection. The `Smithy Gradle Plugin`_ is the best way to get started
+building a Smithy model. First, create a ``smithy-build.json`` file:
+
+.. code-block:: json
+
+    {
+        "version": "1.0"
+    }
+
+Then create a new ``build.gradle.kts`` file:
+
+.. code-block:: kotlin
+
+    plugins {
+        id("software.amazon.smithy").version("0.5.1")
+    }
+
+    repositories {
+        mavenLocal()
+        mavenCentral()
+    }
+
+    dependencies {
+        implementation("software.amazon.smithy:smithy-model:[1.0, 2.0[")
+    }
+
+    configure<software.amazon.smithy.gradle.SmithyExtension> {
+        // Uncomment this to use a custom projection when building the JAR.
+        // projection = "foo"
+    }
+
+    // Uncomment to disable creating a JAR.
+    //tasks["jar"].enabled = false
+
+Finally, copy the weather model to ``model/weather.smithy`` and
+then run ``gradle build`` (make sure you have `gradle installed`_).
+
 Next steps
 ==========
 
@@ -689,15 +732,64 @@ That's it! We just created a simple, read-only, ``Weather`` service.
 1. Try adding a "create" lifecycle operation to ``City``.
 2. Try adding a "delete" lifecycle operation to ``City``.
 3. Try adding :ref:`HTTP binding traits <http-traits>` to the API.
+4. Try adding :ref:`tags <tags-trait>` to shapes and filtering them out with
+   :ref:`excludeShapesByTag <excludeShapesByTag-transform>`.
 
 There's plenty more to explore in Smithy. The
 :ref:`Smithy specification <specification>` can teach you everything you need
-to know about Smithy.
-
+to know about Smithy models. :ref:`Building Smithy Models <building-models>`
+can teach you more about the build process, including how to use
+transformations, projections, plugins, and more. For more sample build
+configurations, see the `examples directory`_ of the Smithy Gradle plugin
+repository.
 
 Complete example
 ================
 
+If you followed all the steps in this guide, you should have three files, laid
+out like so::
+
+    .
+    ├── build.gradle.kts
+    ├── model
+    │   └── weather.smithy
+    └── smithy-build.json
+
+The ``smithy-build.json`` should have the following contents:
+
+.. code-block:: json
+
+    {
+        "version": "1.0"
+    }
+
+The ``build.gradle.kts`` should have the following contents:
+
+.. code-block:: kotlin
+
+    plugins {
+        id("software.amazon.smithy").version("0.5.1")
+    }
+
+    repositories {
+        mavenLocal()
+        mavenCentral()
+    }
+
+    dependencies {
+        implementation("software.amazon.smithy:smithy-model:__smithy_version__")
+    }
+
+    configure<software.amazon.smithy.gradle.SmithyExtension> {
+        // Uncomment this to use a custom projection when building the JAR.
+        // projection = "foo"
+    }
+
+    // Uncomment to disable creating a JAR.
+    //tasks["jar"].enabled = false
+
+Finally, the complete ``weather.smithy`` model should look like:
+
 .. tabs::
 
     .. code-tab:: smithy
@@ -1095,4 +1187,7 @@ Complete example
             }
         }
 
+.. _examples directory: https://github.com/awslabs/smithy-gradle-plugin/tree/master/examples
 .. _Tagged union: https://en.wikipedia.org/wiki/Tagged_union
+.. _Smithy Gradle Plugin: https://github.com/awslabs/smithy-gradle-plugin/
+.. _gradle installed: https://gradle.org/install/