Add description of what exists today

Closes #819

docs/source/1.0/guides/converting-to-openapi.rst

@@ -1,3 +1,5 @@
+.. _smithy-to-openapi:
+
 ============================
 Converting Smithy to OpenAPI
 ============================

docs/source/1.0/guides/generating-cloudformation-resources.rst

@@ -1,3 +1,5 @@
+.. _smithy-to-cloudformation:
+
 ======================================================
 Generating CloudFormation Resource Schemas from Smithy
 ======================================================

docs/source/implementations.rst

@@ -0,0 +1,215 @@
+===================================
+Smithy projects and implementations
+===================================
+
+This document provides an overview of known Smithy implementations and
+projects.
+
+Each project provides a *Status* with the following meanings:
+
+* **1.x** / **2.x** / etc: The major version of a stable implementation.
+* **0.x**: The implementation is not yet stable and likely will change.
+  These pre-release projects may lack polish and may not be easy to use.
+* **WIP**: Work in progress; the implementation is not yet stable and may
+  not be usable.
+
+
+-----------------
+Smithy meta model
+-----------------
+
+.. list-table::
+    :header-rows: 1
+    :widths: 25 15 10 50
+
+    * - Project
+      - Language
+      - Status
+      - Description
+    * - :ref:`specification`
+      - N/A
+      - 1.x
+      - The Smithy specification defines Smithy and its capabilities.
+    * - `Reference implementation <https://github.com/awslabs/smithy>`_
+      - Java
+      - 1.x
+      - The reference implementation of Smithy's metamodel, transformation
+        tooling, and code generators is implemented in Java.
+    * - `Smithy Diff <https://github.com/awslabs/smithy/tree/main/smithy-diff>`_
+      - Java
+      - 1.x
+      - Smithy Diff is a tool used to compare two Smithy models to check
+        for backward compatibility issues. Smithy Diff can be run via a
+        Java library or via the Smithy CLI.
+    * - `Atelier <https://github.com/johnstonskj/rust-atelier>`_
+      - Rust
+      - WIP
+      - A Rust implementation of the Smithy IDL.
+
+
+-----------
+IDE Support
+-----------
+
+.. list-table::
+    :header-rows: 1
+    :widths: 25 15 10 50
+
+    * - Project
+      - Language
+      - Status
+      - Description
+    * - `Visual Studio Code plugin <https://github.com/awslabs/smithy-vscode>`_
+      - Java
+      - WIP
+      - A Visual Studio Code extension to recognize and highlight the
+        Smithy IDL. It can also be used as a TextMate bundle in TextMate
+        and IntelliJ using a third-party plugin.
+    * - `IntelliJ plugin <https://github.com/awslabs/smithy-intellij>`_
+      - Java
+      - WIP
+      - Smithy IntelliJ provides IDE integration for the Smithy IDL within
+        IntelliJ IDEA. It utilizes smithy-language-server for its Language
+        Server Protocol implementation.
+    * - `Smithy LSP <https://github.com/awslabs/smithy-language-server>`_
+      - Java
+      - WIP
+      - A Language Server Protocol implementation for the Smithy IDL.
+
+
+-------------
+Build tooling
+-------------
+
+.. list-table::
+    :header-rows: 1
+    :widths: 25 15 10 50
+
+    * - Project
+      - Language
+      - Status
+      - Description
+    * - `Gradle Plugin <https://github.com/awslabs/smithy-gradle-plugin>`_
+      - Java
+      - 0.x
+      - The Smithy Gradle plugin is currently the only supported way to
+        build Smithy models. `Various example projects <https://github.com/awslabs/smithy-gradle-plugin/tree/main/examples>`_
+        that show how to setup and build Smithy models can be found in the
+        project's repository.
+    * - `Smithy CLI <https://github.com/awslabs/smithy/tree/main/smithy-cli>`_
+      - Java
+      - 1.x*
+      - The Smithy CLI is used to load, validate, diff, and transform
+        Smithy models. The CLI is used to power Smithy's Gradle plugin,
+        and used for other build tooling within Amazon. However, the CLI
+        is still incubating and not yet distributed as a standalone tool.
+
+        The CLI can be built from within the Smithy git repository using Gradle
+        via:
+
+        .. code-block:: none
+
+            ./gradlew :smithy-cli:runtime
+
+        And then used via:
+
+        .. code-block:: none
+
+            cd smithy-cli/build/runtime/bin
+            ./smithy-cli --help
+
+
+---------------
+Code generators
+---------------
+
+The following code generators are in early development. There's no guarantee
+of polish or that they work for all use cases.
+
+.. list-table::
+    :header-rows: 1
+    :widths: 25 15 10 50
+
+    * - Project
+      - Language
+      - Status
+      - Description
+    * - `TypeScript client and server codegen <https://github.com/awslabs/smithy-typescript>`_
+      - Java
+      - 0.x
+      - TypeScript client and server code generation for Smithy.
+    * - `Go client codegen <https://github.com/awslabs/smithy-go>`_
+      - Java
+      - 0.x
+      - Go client code generation for Smithy.
+    * - `Rust client codegen <https://github.com/awslabs/smithy-rs>`_
+      - Java
+      - 0.x
+      - Rust client code generation for Smithy.
+
+
+----------------
+Model converters
+----------------
+
+.. list-table::
+    :header-rows: 1
+    :widths: 25 15 10 50
+
+    * - Project
+      - Language
+      - Status
+      - Description
+    * - :ref:`smithy-to-openapi`
+      - Java
+      - 1.x
+      - Converts Smithy models to OpenAPI. Currently the only supported protocol
+        is :ref:`aws.protocols#restJson1 <aws-restjson1-protocol>`.
+        Amazon API Gateway extensions can be used with Smithy's OpenAPI converter
+        using the `smithy-aws-apigateway-traits <https://search.maven.org/artifact/software.amazon.smithy/smithy-aws-apigateway-traits>`_
+        Maven package.
+    * - `Smithy to JSON Schema <https://github.com/awslabs/smithy/tree/main/smithy-jsonschema>`_
+      - Java
+      - 1.x
+      - Converts Smithy shapes to JSON Schema using a Java library. Because
+        the use cases we've seen so far converting Smithy to JSON Schema have
+        been to facilitate converting Smithy to some other format that uses
+        JSON Schema or some variant of it (like OpenAPI, or CloudFormation
+        resource schemas), no standalone smithy-build plugin to convert Smithy
+        models to JSON Schema is currently provided.
+
+
+------------
+AWS specific
+------------
+
+.. list-table::
+    :header-rows: 1
+    :widths: 25 15 10 50
+
+    * - Project
+      - Language
+      - Status
+      - Description
+    * - :ref:`aws-specifications`
+      - Java
+      - 1.x
+      - Smithy supports various AWS plugins, traits, and specifications,
+        though these are generally only useful to developers within Amazon
+        and AWS.
+    * - `AWS SDK for JavaScript v3 <https://github.com/aws/aws-sdk-js-v3>`_
+      - Java
+      - 1.x
+      - The AWS SDK for JavaScript v3 is built with Smithy.
+    * - `AWS SDK for Go v2 <https://github.com/aws/aws-sdk-go-v2>`_
+      - Java
+      - 1.x
+      - The AWS SDK for Go v2 is built with Smithy.
+    * - `AWS SDK for Rust <https://github.com/awslabs/aws-sdk-rust>`_
+      - Kotlin
+      - 0.x
+      - The AWS SDK for Rust is built with Smithy.
+    * - :ref:`smithy-to-cloudformation`
+      - Java
+      - 1.x
+      - Converts Smithy models to CloudFormation Resource Schemas.

docs/source/index.rst

@@ -6,5 +6,6 @@ Smithy
     :maxdepth: 1
 
     quickstart
+    implementations
     1.0/spec/index
     1.0/guides/index

docs/themes/smithy/landing.html

@@ -130,7 +130,10 @@ <h2>What is the main difference between Smithy and OpenAPI?</h2>
             <p>The primary difference between Smithy and OpenAPI is that Smithy is
                 protocol-agnostic, allowing Smithy to describe a broader range of
                 services, metadata, and capabilities. Smithy can be used alongside
-                OpenAPI by <a href="{{ pathto('guides/converting-to-openapi') }}">converting Smithy models to OpenAPI</a>.</p>
+                OpenAPI by <a href="{{ pathto('1.0/guides/converting-to-openapi') }}">converting Smithy models to OpenAPI</a>.</p>
+
+            <h2 id="status">What can Smithy do today?</h2>
+            <p>See <a href="{{ pathto('implementations') }}">Smithy projects and implementations</a></p>
 
             <section class="relations">
                 <a class="next-page clearfix" href="{{ pathto('quickstart')}}">Quick start -&gt;</a>