From 835cbf84bdf28fdb4b2c4b6efcd1c601a35e5da3 Mon Sep 17 00:00:00 2001 From: JordonPhillips Date: Wed, 27 May 2020 13:10:47 -0700 Subject: [PATCH 1/3] Include more specific build examples and links This updates the README and quickstart guides to include more specific examples on how to use the Gradle plugin to build models as well as links to the examples directory in the plugin repository. --- README.md | 15 ++- .../guides/building-models/build-config.rst | 2 +- .../guides/building-models/gradle-plugin.rst | 6 ++ .../1.0/guides/building-models/index.rst | 2 + docs/source/quickstart.rst | 99 ++++++++++++++++++- 5 files changed, 119 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 03a53686197..7d89a2a68c2 100644 --- a/README.md +++ b/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 diff --git a/docs/source/1.0/guides/building-models/build-config.rst b/docs/source/1.0/guides/building-models/build-config.rst index 016f29234f9..1e5329f8efd 100644 --- a/docs/source/1.0/guides/building-models/build-config.rst +++ b/docs/source/1.0/guides/building-models/build-config.rst @@ -243,7 +243,7 @@ Applies the transforms defined in the given projection names. } -.. excludeShapesByTag-transform: +.. _excludeShapesByTag-transform: excludeShapesByTag ------------------ diff --git a/docs/source/1.0/guides/building-models/gradle-plugin.rst b/docs/source/1.0/guides/building-models/gradle-plugin.rst index 3952e216947..070b38c1620 100644 --- a/docs/source/1.0/guides/building-models/gradle-plugin.rst +++ b/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/ diff --git a/docs/source/1.0/guides/building-models/index.rst b/docs/source/1.0/guides/building-models/index.rst index fd1da9ec0ab..3e3ebeac202 100644 --- a/docs/source/1.0/guides/building-models/index.rst +++ b/docs/source/1.0/guides/building-models/index.rst @@ -1,3 +1,5 @@ +.. _building-models: + ====================== Building Smithy Models ====================== diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst index a21267714ea..6274b073276 100644 --- a/docs/source/quickstart.rst +++ b/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 { + // 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 ` to the API. +4. Try adding :ref:`tags ` to shapes and filtering them out with + :ref:`excludeShapesByTag `. There's plenty more to explore in Smithy. The :ref:`Smithy specification ` can teach you everything you need -to know about Smithy. - +to know about Smithy models. :ref:`Building Smithy 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 { + // 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/ From 800f52219d419f524d1ce833c176b592982bddc1 Mon Sep 17 00:00:00 2001 From: JordonPhillips Date: Wed, 27 May 2020 14:25:45 -0700 Subject: [PATCH 2/3] Fix incorrect shape type in docs --- docs/source/1.0/spec/core/shapes.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/1.0/spec/core/shapes.rst b/docs/source/1.0/spec/core/shapes.rst index 36e1e42f7a6..dec566d95c3 100644 --- a/docs/source/1.0/spec/core/shapes.rst +++ b/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" From f765907a421f315cccd56a9928a1411ecb7cad83 Mon Sep 17 00:00:00 2001 From: JordonPhillips Date: Wed, 27 May 2020 14:28:13 -0700 Subject: [PATCH 3/3] Remove erroneous required in docs --- docs/source/1.0/guides/building-models/build-config.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/1.0/guides/building-models/build-config.rst b/docs/source/1.0/guides/building-models/build-config.rst index 1e5329f8efd..db5addf0a55 100644 --- a/docs/source/1.0/guides/building-models/build-config.rst +++ b/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.