Update documentation

smithy-lang · Feb 27, 2024 · 4a820f8 · 4a820f8
1 parent c5cf133
commit 4a820f8
Show file tree

Hide file tree

Showing 24 changed files with 634 additions and 177 deletions.
diff --git a/2.0/_sources/aws/amazon-apigateway.rst.txt b/2.0/_sources/aws/amazon-apigateway.rst.txt
@@ -418,7 +418,7 @@ operation within the service.
 .. code-block:: json
 
     {
-        "smithy": "1.0",
+        "version": "2.0",
         "shapes": {
             "smithy.example#Weather": {
                 "type": "service",
@@ -531,7 +531,7 @@ The following example defines an operation that uses a mock integration.
 .. code-block:: json
 
     {
-        "smithy": "1.0",
+        "smithy": "2.0",
         "shapes": {
             "smithy.example#MyOperation": {
                 "type": "operation",

diff --git a/2.0/_sources/aws/rules-engine/auth-schemes.rst.txt b/2.0/_sources/aws/rules-engine/auth-schemes.rst.txt
@@ -9,22 +9,12 @@ make it possible to validate configurations for AWS authentication schemes like
 `AWS signature version 4`_. An additional dependency is required to access
 these validators
 
-The following example adds ``smithy-aws-endpoints`` as a Gradle dependency
-to a Smithy project:
+The following example adds ``smithy-aws-endpoints`` as a dependency to a Smithy project:
 
-.. tab:: Gradle
-
-    .. code-block:: kotlin
-
-        dependencies {
-            ...
-            implementation("software.amazon.smithy:smithy-aws-endpoints:__smithy_version__")
-            ...
-        }
-
-.. tab:: smithy-build.json
+.. tab:: Smithy CLI
 
     .. code-block:: json
+        :caption: smithy-build.json
 
         {
             "maven": {
@@ -34,6 +24,30 @@ to a Smithy project:
             }
         }
 
+.. tab:: Gradle
+
+    .. tab:: Kotlin
+
+        .. code-block:: kotlin
+            :caption: build.gradle.kts
+
+            dependencies {
+                ...
+                implementation("software.amazon.smithy:smithy-aws-endpoints:__smithy_version__")
+                ...
+            }
+
+    .. tab:: Groovy
+
+        .. code-block:: groovy
+            :caption: build.gradle
+
+            dependencies {
+                ...
+                implementation 'software.amazon.smithy:smithy-aws-endpoints:__smithy_version__'
+                ...
+            }
+
 .. _rules-engine-aws-authscheme-validator-sigv4:
 
 -----------------------------------------

diff --git a/2.0/_sources/aws/rules-engine/built-ins.rst.txt b/2.0/_sources/aws/rules-engine/built-ins.rst.txt
@@ -11,19 +11,10 @@ dependency is required to access these functions:
 The following example adds ``smithy-aws-endpoints`` as a Gradle dependency
 to a Smithy project:
 
-.. tab:: Gradle
-
-    .. code-block:: kotlin
-
-        dependencies {
-            ...
-            implementation("software.amazon.smithy:smithy-aws-endpoints:__smithy_version__")
-            ...
-        }
-
-.. tab:: smithy-build.json
+.. tab:: Smithy CLI
 
     .. code-block:: json
+        :caption: smithy-build.json
 
         {
             "maven": {
@@ -33,6 +24,29 @@ to a Smithy project:
             }
         }
 
+.. tab:: Gradle
+
+    .. tab:: Kotlin
+
+        .. code-block:: kotlin
+            :caption: build.gradle.kts
+
+            dependencies {
+                ...
+                implementation("software.amazon.smithy:smithy-aws-endpoints:__smithy_version__")
+                ...
+            }
+
+    .. tab:: Groovy
+
+        .. code-block:: groovy
+            :caption: build.gradle
+
+            dependencies {
+                ...
+                implementation 'software.amazon.smithy:smithy-aws-endpoints:__smithy_version__'
+                ...
+            }
 
 .. _rules-engine-aws-built-ins-region:
 

diff --git a/2.0/_sources/aws/rules-engine/library-functions.rst.txt b/2.0/_sources/aws/rules-engine/library-functions.rst.txt
@@ -9,22 +9,13 @@ make it possible to integrate AWS concepts like `Amazon Resource Names (ARNs)`_
 and `Partitions`_. An additional dependency is required to access these
 functions:
 
-The following example adds ``smithy-aws-endpoints`` as a Gradle dependency
+The following example adds ``smithy-aws-endpoints`` as a dependency
 to a Smithy project:
 
-.. tab:: Gradle
-
-    .. code-block:: kotlin
-
-        dependencies {
-            ...
-            implementation("software.amazon.smithy:smithy-aws-endpoints:__smithy_version__")
-            ...
-        }
-
-.. tab:: smithy-build.json
+.. tab:: Smithy CLI
 
     .. code-block:: json
+        :caption: smithy-build.json
 
         {
             "maven": {
@@ -34,6 +25,30 @@ to a Smithy project:
             }
         }
 
+.. tab:: Gradle
+
+    .. tab:: Kotlin
+
+        .. code-block:: kotlin
+            :caption: build.gradle.kts
+
+            dependencies {
+                ...
+                implementation("software.amazon.smithy:smithy-aws-endpoints:__smithy_version__")
+                ...
+            }
+
+    .. tab:: Groovy
+
+        .. code-block:: groovy
+            :caption: build.gradle
+
+            dependencies {
+                ...
+                implementation 'software.amazon.smithy:smithy-aws-endpoints:__smithy_version__'
+                ...
+            }
+
 .. _rules-engine-aws-library-awsPartition:
 
 ``aws.partition`` function

diff --git a/2.0/_sources/guides/building-codegen/configuring-the-generator.rst.txt b/2.0/_sources/guides/building-codegen/configuring-the-generator.rst.txt
@@ -12,6 +12,7 @@ Smithy code generators are configured using plugins defined in
 smithy-build.json files. For example:
 
 .. code-block:: json
+    :caption: smithy-build.json
     :emphasize-lines: 4-9
 
     {

diff --git a/2.0/_sources/guides/building-codegen/overview-and-concepts.rst.txt b/2.0/_sources/guides/building-codegen/overview-and-concepts.rst.txt
@@ -25,8 +25,9 @@ Interfaces (SPI).
 Consider the following smithy-build.json file:
 
 .. code-block:: json
+    :caption: smithy-build.json
 
-   {
+    {
        "version": "1.0",
        "plugins": {
            "foo-client-codegen": {
@@ -36,7 +37,7 @@ Consider the following smithy-build.json file:
                "edition": "2022"
            }
        }
-   }
+    }
 
 This file tells Smithy-Build to generate a hypothetical Foo language
 client using the ``foo-client-codegen`` plugin found on the classpath.
@@ -149,8 +150,9 @@ implementation. For example, here's how service code generation could be
 configured for a Java code generator:
 
 .. code-block:: json
+    :caption: smithy-build.json
 
-   {
+    {
        "version": "1.0",
        "projections": {
            "source": {
@@ -164,7 +166,7 @@ configured for a Java code generator:
                }
            }
        }
-   }
+    }
 
 
 Client generation

diff --git a/2.0/_sources/guides/gradle-plugin/gradle-migration-guide.rst.txt b/2.0/_sources/guides/gradle-plugin/gradle-migration-guide.rst.txt
@@ -34,7 +34,7 @@ your project.
         plugins {
         -     id("software.amazon.smithy").version("0.7.0")
         +     `java`
-        +     id("software.amazon.smithy.gradle.smithy-jar").version("0.10.0")
+        +     id("software.amazon.smithy.gradle.smithy-jar").version("__smithy_gradle_version__")
         }
 
 .. tab:: Groovy
@@ -45,7 +45,7 @@ your project.
         plugins {
         -      id 'software.amazon.smithy' version '0.7.0'
         +      id 'java'
-        +      id 'software.amazon.smithy.gradle.smithy-jar' version '0.10.0'
+        +      id 'software.amazon.smithy.gradle.smithy-jar' version '__smithy_gradle_version__'
         }
 
 Remove Buildscript Dependencies

diff --git a/2.0/_sources/guides/gradle-plugin/index.rst.txt b/2.0/_sources/guides/gradle-plugin/index.rst.txt
@@ -51,7 +51,7 @@ The following example configures a project to use the ``smithy-base`` Gradle plu
         :caption: build.gradle.kts
 
         plugins {
-            id("software.amazon.smithy.gradle.smithy-base").version("0.10.0")
+            id("software.amazon.smithy.gradle.smithy-base").version("__smithy_gradle_version__")
         }
 
 .. tab:: Groovy
@@ -60,7 +60,7 @@ The following example configures a project to use the ``smithy-base`` Gradle plu
         :caption: build.gradle
 
         plugins {
-            id 'software.amazon.smithy.gradle.smithy-base' version '0.10.0'
+            id 'software.amazon.smithy.gradle.smithy-base' version '__smithy_gradle_version__'
         }
 
 
@@ -124,7 +124,7 @@ The following example ``build.gradle.kts`` will build a Smithy model using a
 
         plugins {
             `java-library`
-            id("software.amazon.smithy.gradle.smithy-jar").version("0.10.0")
+            id("software.amazon.smithy.gradle.smithy-jar").version("__smithy_gradle_version__")
         }
 
         // The SmithyExtension is used to customize the build. This example
@@ -152,7 +152,7 @@ The following example ``build.gradle.kts`` will build a Smithy model using a
 
         plugins {
             id 'java-library'
-            'software.amazon.smithy.gradle.smithy-jar' version '0.10.0'
+            'software.amazon.smithy.gradle.smithy-jar' version '__smithy_gradle_version__'
         }
 
         // The SmithyExtension is used to customize the build. This example
@@ -198,7 +198,7 @@ build using the "external" projection.
 
             plugins {
                 `java-library`
-                id("software.amazon.smithy.gradle.smithy-jar").version("0.10.0")
+                id("software.amazon.smithy.gradle.smithy-jar").version("__smithy_gradle_version__")
             }
 
             repositories {
@@ -231,7 +231,7 @@ build using the "external" projection.
 
             plugins {
                 id 'java-library'
-                id 'software.amazon.smithy.gradle.smithy-jar' version '0.10.0'
+                id 'software.amazon.smithy.gradle.smithy-jar' version '__smithy_gradle_version__'
             }
 
             repositories {

diff --git a/2.0/_sources/guides/model-linters.rst.txt b/2.0/_sources/guides/model-linters.rst.txt
@@ -14,15 +14,45 @@ that is configurable. Linter implementations are found in code. The
 `smithy-linters`_ package in Maven Central contains several linters that
 can be used to apply additional validation to Smithy models.
 
-The following example adds ``smithy-linters`` as a Gradle dependency
-to a ``build.gradle.kts`` file:
+The following example adds ``smithy-linters`` as a dependency to a Smithy project:
 
-.. code-block:: kotlin
+.. tab:: Smithy CLI
+
+    .. code-block:: json
+        :caption: smithy-build.json
+
+        {
+            "...": "...",
+            "maven": {
+                "dependencies": [
+                    "software.amazon.smithy:smithy-linters:__smithy_version__"
+                ]
+            },
+            "...": "..."
+        }
+
+.. tab:: Gradle
+
+    .. tab:: Kotlin
+
+        .. code-block:: kotlin
+            :caption: build.gradle.kts
+
+            dependencies {
+                ...
+                implementation("software.amazon.smithy:smithy-linters:__smithy_version__")
+            }
+
+    .. tab:: Groovy
+
+        .. code-block:: groovy
+            :caption: build.gradle
+
+            dependencies {
+                ...
+                implementation 'software.amazon.smithy:smithy-linters:__smithy_version__'
+            }
 
-    dependencies {
-        implementation("software.amazon.smithy:smithy-model:__smithy_version__")
-        implementation("software.amazon.smithy:smithy-linters:__smithy_version__")
-    }
 
 After the dependency is added and available on the Java classpath, validators
 defined in the package and registered using `Java SPI`_ are available for

diff --git a/2.0/_sources/guides/model-translations/converting-to-openapi.rst.txt b/2.0/_sources/guides/model-translations/converting-to-openapi.rst.txt
@@ -165,7 +165,7 @@ OpenAPI specifications from Smithy models.
                 java
                 // Use the `smithy-jar` plugin if you also want to package
                 // smithy models into the JAR created by the `java` plugin.
-                id("software.amazon.smithy-base").version("0.10.0")
+                id("software.amazon.smithy-base").version("__smithy_gradle_version__")
             }
 
             dependencies {
@@ -184,7 +184,7 @@ OpenAPI specifications from Smithy models.
                 id 'java'
                 // Use the `smithy-jar` plugin if you also want to package
                 // smithy models into the JAR created by the `java` plugin.
-                id 'software.amazon.smithy-base' version '0.10.0'
+                id 'software.amazon.smithy-base' version '__smithy_gradle_version__'
             }
 
             dependencies {
@@ -1245,7 +1245,7 @@ of a Smithy model into an OpenAPI specification.
 
             plugins {
                 java
-                id("software.amazon.smithy.gradle.smithy-base").version("0.10.0")
+                id("software.amazon.smithy.gradle.smithy-base").version("__smithy_gradle_version__")
             }
 
             dependencies {
@@ -1263,7 +1263,7 @@ of a Smithy model into an OpenAPI specification.
 
             plugins {
                 id 'java'
-                id 'software.amazon.smithy.gradle.smithy-base' version '0.10.0'
+                id 'software.amazon.smithy.gradle.smithy-base' version '__smithy_gradle_version__'
             }
 
             dependencies {