Add index of all traits

This add an index of all existing traits to the specifications page.
This makes it way easier to find the docs for a trait you know about
without having to figure out what class of trait it is, or whether
it lives in aws or somewhere else.

docs/smithy/__init__.py

@@ -8,10 +8,13 @@
 from docutils.statemachine import StringList
 from docutils.writers.html4css1 import HTMLTranslator as BaseTranslator
 
+from .traitindex import setup_smithy_trait_index
+
 
 def setup(app):
     app.set_translator('html', HTMLTranslator)
     app.add_directive("text-figure", TextFigure)
+    setup_smithy_trait_index(app)
 
 # Finds the href part of a header.
 HREF = re.compile('href="([^"]+)"')

docs/smithy/traitindex.py

@@ -0,0 +1,116 @@
+from docutils import nodes
+from docutils.parsers.rst import Directive
+
+from sphinx.locale import _
+
+SMITHY_TRAITS_ATTR = "smithy_traits"
+
+
+# Placeholder node that will be replaced with the trait index.
+class SmithyTraitIndexNode(nodes.General, nodes.Element):
+    pass
+
+
+# Directive that places a SmithyTraitIndexNode in the document.
+# Usage: .. smithy-trait-index::
+class SmithyTraitIndexDirective(Directive):
+    def run(self):
+        return [SmithyTraitIndexNode("")]
+
+
+# Directive that marks the location of a smithy trait in the docs.
+# Usage: .. smithy-trait: ns.example#shapeId
+class SmithyTraitDirective(Directive):
+
+    # Makes the shape id argument required
+    required_arguments = 1
+
+    def run(self):
+        env = self.state.document.settings.env
+        shape_id = self.arguments[0]
+
+        # Make the shape id url-friendly
+        stripped_shape_id = shape_id.strip().replace("#", "-").replace(".", "-").lower()
+
+        # Create a new target node that can be referenced
+        target_id = stripped_shape_id + "-trait"
+        target_node = nodes.target("", "", ids=[target_id])
+
+        # Add a list of the smithy trait targets to the envirnonment so that
+        # they can be referenced later when building the trait index.
+        if not hasattr(env, SMITHY_TRAITS_ATTR):
+            env.smithy_traits = []
+
+        env.smithy_traits.append(
+            {
+                "docname": env.docname,
+                "target": target_node,
+                "shape_id": shape_id,
+            }
+        )
+
+        return [target_node]
+
+
+# If the source file changes, remove any cached smithy traits for it. If there
+# are any remaining in the file itself, they'll be re-added in the normal way.
+def purge_smithy_traits(app, env, docname):
+    if not hasattr(env, SMITHY_TRAITS_ATTR):
+        return
+    env.smithy_traits = [t for t in env.smithy_traits if t["docname"] != docname]
+
+
+# In the case of a parallel build, there will be multiple envs. This handles
+# merging all the smithy traits into a single list at the end.
+def merge_smithy_traits(app, env, docnames, other):
+    if not hasattr(env, SMITHY_TRAITS_ATTR):
+        env.smithy_traits = []
+    if hasattr(other, SMITHY_TRAITS_ATTR):
+        env.smithy_traits.extend(other.smithy_traits)
+
+
+# Generates a list of links to known smithy traits, replacing any
+# SmithyTraitIndexNodes
+def process_smithy_nodes(app, doctree, fromdocname):
+    env = app.builder.env
+
+    if not hasattr(env, SMITHY_TRAITS_ATTR):
+        env.smithy_traits = []
+
+    for node in doctree.traverse(SmithyTraitIndexNode):
+        new_index_node = nodes.bullet_list()
+
+        smithy_traits = sorted(env.smithy_traits, key=lambda x: x["shape_id"])
+
+        for smithy_trait_info in smithy_traits:
+            shape_id = smithy_trait_info["shape_id"]
+
+            # Create a reference node, which becomes a link with the text being
+            # the shape id.
+            ref_node = nodes.reference("", "")
+            inner_node = nodes.emphasis(_(shape_id), _(shape_id))
+            ref_node["refdocname"] = smithy_trait_info["docname"]
+            ref_node["refuri"] = app.builder.get_relative_uri(
+                fromdocname, smithy_trait_info["docname"]
+            )
+            ref_node["refuri"] += "#" + smithy_trait_info["target"]["refid"]
+            ref_node.append(inner_node)
+
+            # Wrap the reference in a paragraph and construct a list item from it.
+            para = nodes.paragraph()
+            para += ref_node
+            list_item = nodes.list_item()
+            list_item += para
+
+            new_index_node.append(list_item)
+
+        node.replace_self(new_index_node)
+
+
+def setup_smithy_trait_index(app):
+    app.add_node(SmithyTraitIndexNode)
+    app.add_directive("smithy-trait", SmithyTraitDirective)
+    app.add_directive("smithy-trait-index", SmithyTraitIndexDirective)
+    app.connect("doctree-resolved", process_smithy_nodes)
+    app.connect("env-purge-doc", purge_smithy_traits)
+    app.connect("env-merge-info", merge_smithy_traits)

docs/source/1.0/spec/aws/amazon-apigateway.rst

@@ -11,6 +11,7 @@ schemes, and OpenAPI specifications.
     :backlinks: none
 
 
+.. smithy-trait:: aws.apigateway#apiKeySource
 .. _aws.apigateway#apiKeySource-trait:
 
 -------------------------------------
@@ -78,6 +79,7 @@ The following example sets the ``X-API-Key`` header as the API key source.
     customers.
 
 
+.. smithy-trait:: aws.apigateway#authorizers
 .. _aws.apigateway#authorizers-trait:
 
 ------------------------------------
@@ -217,6 +219,7 @@ An *authorizer* definition is a structure that supports the following members:
     customers.
 
 
+.. smithy-trait:: aws.apigateway#authorizer
 .. _aws.apigateway#authorizer-trait:
 
 -----------------------------------
@@ -242,6 +245,7 @@ Value type
     customers.
 
 
+.. smithy-trait:: aws.apigateway#requestValidator
 .. _aws.apigateway#requestValidator-trait:
 
 -----------------------------------------
@@ -313,6 +317,7 @@ Then following example enables request validation on a service:
     customers.
 
 
+.. smithy-trait:: aws.apigateway#integration
 .. _aws.apigateway#integration-trait:
 
 ------------------------------------
@@ -489,6 +494,7 @@ operation within the service.
     customers.
 
 
+.. smithy-trait:: aws.apigateway#mockIntegration
 .. _aws.apigateway#mockIntegration-trait:
 
 ----------------------------------------

docs/source/1.0/spec/aws/aws-auth.rst

@@ -12,6 +12,7 @@ This document defines AWS authentication schemes.
     :backlinks: none
 
 
+.. smithy-trait:: aws.auth#sigv4
 .. _aws.auth#sigv4-trait:
 
 ------------------------
@@ -79,6 +80,7 @@ Trait value
         }
 
 
+.. smithy-trait:: aws.auth#unsignedPayload
 .. _aws.auth#unsignedPayload-trait:
 
 ----------------------------------
@@ -143,6 +145,7 @@ literal string ``UNSIGNED-PAYLOAD`` is used when constructing a
 `x-amz-content-sha256`_ header when sending an HTTP request.
 
 
+.. smithy-trait:: aws.auth#cognitoUserPools
 .. _aws.auth#cognitoUserPools-trait:
 
 -----------------------------------

docs/source/1.0/spec/aws/aws-cloudformation.rst

@@ -24,6 +24,7 @@ Interface`_ to build, register, and deploy `resource providers`_.
     :backlinks: none
 
 
+.. smithy-trait:: aws.cloudformation#cfnResource
 .. _aws.cloudformation#cfnResource-trait:
 
 ----------------------------------------
@@ -139,6 +140,7 @@ of these structures can be excluded by applying the :ref:`aws.cloudformation#cfn
     derived.
 
 
+.. smithy-trait:: aws.cloudformation#cfnExcludeProperty
 .. _aws.cloudformation#cfnExcludeProperty-trait:
 
 -----------------------------------------------
@@ -330,6 +332,7 @@ The computed resource property mutabilities are:
       - + Specified in the ``create`` lifecycle via ``CreateFooRequest``.
 
 
+.. smithy-trait:: aws.cloudformation#cfnMutability
 .. _aws.cloudformation#cfnMutability-trait:
 
 ------------------------------------------
@@ -531,6 +534,7 @@ derivable ``secret`` and ``password`` properties as write only:
         }
 
 
+.. smithy-trait:: aws.cloudformation#cfnName
 .. _aws.cloudformation#cfnName-trait:
 
 ------------------------------------
@@ -573,6 +577,8 @@ the following property names are derived from it:
     "bar"
     "Tags"
 
+
+.. smithy-trait:: aws.cloudformation#cfnAdditionalIdentifier
 .. _aws.cloudformation#cfnAdditionalIdentifier-trait:
 
 ----------------------------------------------------

docs/source/1.0/spec/aws/aws-core.rst

@@ -11,6 +11,7 @@ AWS products like AWS CloudFormation and tools like the AWS SDKs.
     :backlinks: none
 
 
+.. smithy-trait:: aws.api#service
 .. _aws.api#service-trait:
 
 -------------------------
@@ -256,6 +257,7 @@ a static, unique identifier. :ref:`service-sdk-id` should be used for those
 purposes. Additionally, this value can be used to attempt to resolve endpoints.
 
 
+.. smithy-trait:: aws.api#arn
 .. _aws.api#arn-trait:
 
 ---------------------
@@ -492,6 +494,8 @@ resource.
             }
         }
 
+
+.. smithy-trait:: aws.api#arnReference
 .. _aws.api#arnReference-trait:
 
 ------------------------------
@@ -607,6 +611,8 @@ previous example:
             }
         }
 
+
+.. smithy-trait:: aws.api#data
 .. _aws.api#data-trait:
 
 ----------------------
@@ -739,6 +745,7 @@ applied through the ``aws.api#data`` trait.
         :ref:`sensitive-trait`.
 
 
+.. smithy-trait:: aws.api#controlPlane
 .. _aws.api#controlPlane-trait:
 
 ------------------------------
@@ -793,6 +800,8 @@ plane unless an operation or resource is marked with the
             }
         }
 
+
+.. smithy-trait:: aws.api#dataPlane
 .. _aws.api#dataPlane-trait:
 
 ---------------------------
@@ -860,6 +869,7 @@ automatically discover, cache, and connect to service endpoints. The
 following traits provide the information needed to perform this.
 
 
+.. smithy-trait:: aws.api#clientEndpointDiscovery
 .. _client-endpoint-discovery-trait:
 
 ``aws.api#clientEndpointDiscovery`` trait
@@ -908,6 +918,7 @@ The operation output MUST contain a member ``Endpoints`` that is a list of
 - a ``long`` member named ``CachePeriodInMinutes``
 
 
+.. smithy-trait:: aws.api#clientDiscoveredEndpoint
 .. _client-discovered-endpoint-trait:
 
 ``aws.api#clientDiscoveredEndpoint`` trait
@@ -940,6 +951,7 @@ following members:
         discover a more specific endpoint.
 
 
+.. smithy-trait:: aws.api#clientEndpointDiscoveryId
 .. _client-endpoint-discovery-id-trait:
 
 ``aws.api#clientEndpointDiscoveryId`` trait

docs/source/1.0/spec/aws/aws-ec2-query-protocol.rst

@@ -12,6 +12,7 @@ This specification defines the ``aws.protocols#ec2`` protocol.
     :backlinks: none
 
 
+.. smithy-trait:: aws.protocols#ec2Query
 .. _aws.protocols#ec2Query-trait:
 
 --------------------------------
@@ -68,6 +69,7 @@ Value type
         }
 
 
+.. smithy-trait:: aws.protocols#ec2QueryName
 .. _aws.protocols#ec2QueryName-trait:
 
 ------------------------------------

docs/source/1.0/spec/aws/aws-iam.rst

@@ -23,6 +23,7 @@ more information, see :ref:`deriving-condition-keys`.
     :backlinks: none
 
 
+.. smithy-trait:: aws.iam#actionPermissionDescription
 .. _aws.iam#actionPermissionDescription-trait:
 
 ---------------------------------------------
@@ -62,6 +63,8 @@ Value type
             }
         }
 
+
+.. smithy-trait:: aws.iam#conditionKeys
 .. _aws.iam#conditionKeys-trait:
 
 -------------------------------
@@ -169,6 +172,7 @@ The following example's ``MyResource`` resource has the
     without being defined on the service.
 
 
+.. smithy-trait:: aws.iam#defineConditionKeys
 .. _aws.iam#defineConditionKeys-trait:
 
 -------------------------------------
@@ -312,6 +316,7 @@ Condition keys in IAM policies can be evaluated with `condition operators`_.
       - An unordered list of String types.
 
 
+.. smithy-trait:: aws.iam#disableConditionKeyInference
 .. _aws.iam#disableConditionKeyInference-trait:
 
 ----------------------------------------------
@@ -392,6 +397,8 @@ condition key inference disabled.
             }
         }
 
+
+.. smithy-trait:: aws.iam#requiredActions
 .. _aws.iam#requiredActions-trait:
 
 ---------------------------------

docs/source/1.0/spec/aws/aws-json-1_0-protocol.rst

@@ -12,6 +12,7 @@ This specification defines the ``aws.protocols#awsJson1_0`` protocol.
     :backlinks: none
 
 
+.. smithy-trait:: aws.protocols#awsJson1_0
 .. _aws.protocols#awsJson1_0-trait:
 
 ----------------------------------

docs/source/1.0/spec/aws/aws-json-1_1-protocol.rst

@@ -12,6 +12,7 @@ This specification defines the ``aws.protocols#awsJson1_1`` protocol.
     :backlinks: none
 
 
+.. smithy-trait:: aws.protocols#awsJson1_1
 .. _aws.protocols#awsJson1_1-trait:
 
 ----------------------------------