Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add index of all traits #876

Merged
merged 1 commit into from
Aug 10, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions docs/smithy/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -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="([^"]+)"')
Expand Down
116 changes: 116 additions & 0 deletions docs/smithy/traitindex.py
Original file line number Diff line number Diff line change
@@ -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)
6 changes: 6 additions & 0 deletions docs/source/1.0/spec/aws/amazon-apigateway.rst
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ schemes, and OpenAPI specifications.
:backlinks: none


.. smithy-trait:: aws.apigateway#apiKeySource
.. _aws.apigateway#apiKeySource-trait:

-------------------------------------
Expand Down Expand Up @@ -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:

------------------------------------
Expand Down Expand Up @@ -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:

-----------------------------------
Expand All @@ -242,6 +245,7 @@ Value type
customers.


.. smithy-trait:: aws.apigateway#requestValidator
.. _aws.apigateway#requestValidator-trait:

-----------------------------------------
Expand Down Expand Up @@ -313,6 +317,7 @@ Then following example enables request validation on a service:
customers.


.. smithy-trait:: aws.apigateway#integration
.. _aws.apigateway#integration-trait:

------------------------------------
Expand Down Expand Up @@ -489,6 +494,7 @@ operation within the service.
customers.


.. smithy-trait:: aws.apigateway#mockIntegration
.. _aws.apigateway#mockIntegration-trait:

----------------------------------------
Expand Down
3 changes: 3 additions & 0 deletions docs/source/1.0/spec/aws/aws-auth.rst
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ This document defines AWS authentication schemes.
:backlinks: none


.. smithy-trait:: aws.auth#sigv4
.. _aws.auth#sigv4-trait:

------------------------
Expand Down Expand Up @@ -79,6 +80,7 @@ Trait value
}


.. smithy-trait:: aws.auth#unsignedPayload
.. _aws.auth#unsignedPayload-trait:

----------------------------------
Expand Down Expand Up @@ -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:

-----------------------------------
Expand Down
6 changes: 6 additions & 0 deletions docs/source/1.0/spec/aws/aws-cloudformation.rst
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ Interface`_ to build, register, and deploy `resource providers`_.
:backlinks: none


.. smithy-trait:: aws.cloudformation#cfnResource
.. _aws.cloudformation#cfnResource-trait:

----------------------------------------
Expand Down Expand Up @@ -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:

-----------------------------------------------
Expand Down Expand Up @@ -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:

------------------------------------------
Expand Down Expand Up @@ -531,6 +534,7 @@ derivable ``secret`` and ``password`` properties as write only:
}


.. smithy-trait:: aws.cloudformation#cfnName
.. _aws.cloudformation#cfnName-trait:

------------------------------------
Expand Down Expand Up @@ -573,6 +577,8 @@ the following property names are derived from it:
"bar"
"Tags"


.. smithy-trait:: aws.cloudformation#cfnAdditionalIdentifier
.. _aws.cloudformation#cfnAdditionalIdentifier-trait:

----------------------------------------------------
Expand Down
12 changes: 12 additions & 0 deletions docs/source/1.0/spec/aws/aws-core.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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:

-------------------------
Expand Down Expand Up @@ -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:

---------------------
Expand Down Expand Up @@ -492,6 +494,8 @@ resource.
}
}


.. smithy-trait:: aws.api#arnReference
.. _aws.api#arnReference-trait:

------------------------------
Expand Down Expand Up @@ -607,6 +611,8 @@ previous example:
}
}


.. smithy-trait:: aws.api#data
.. _aws.api#data-trait:

----------------------
Expand Down Expand Up @@ -739,6 +745,7 @@ applied through the ``aws.api#data`` trait.
:ref:`sensitive-trait`.


.. smithy-trait:: aws.api#controlPlane
.. _aws.api#controlPlane-trait:

------------------------------
Expand Down Expand Up @@ -793,6 +800,8 @@ plane unless an operation or resource is marked with the
}
}


.. smithy-trait:: aws.api#dataPlane
.. _aws.api#dataPlane-trait:

---------------------------
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions docs/source/1.0/spec/aws/aws-ec2-query-protocol.rst
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ This specification defines the ``aws.protocols#ec2`` protocol.
:backlinks: none


.. smithy-trait:: aws.protocols#ec2Query
.. _aws.protocols#ec2Query-trait:

--------------------------------
Expand Down Expand Up @@ -68,6 +69,7 @@ Value type
}


.. smithy-trait:: aws.protocols#ec2QueryName
.. _aws.protocols#ec2QueryName-trait:

------------------------------------
Expand Down
7 changes: 7 additions & 0 deletions docs/source/1.0/spec/aws/aws-iam.rst
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ more information, see :ref:`deriving-condition-keys`.
:backlinks: none


.. smithy-trait:: aws.iam#actionPermissionDescription
.. _aws.iam#actionPermissionDescription-trait:

---------------------------------------------
Expand Down Expand Up @@ -62,6 +63,8 @@ Value type
}
}


.. smithy-trait:: aws.iam#conditionKeys
.. _aws.iam#conditionKeys-trait:

-------------------------------
Expand Down Expand Up @@ -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:

-------------------------------------
Expand Down Expand Up @@ -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:

----------------------------------------------
Expand Down Expand Up @@ -392,6 +397,8 @@ condition key inference disabled.
}
}


.. smithy-trait:: aws.iam#requiredActions
.. _aws.iam#requiredActions-trait:

---------------------------------
Expand Down
1 change: 1 addition & 0 deletions docs/source/1.0/spec/aws/aws-json-1_0-protocol.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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:

----------------------------------
Expand Down
1 change: 1 addition & 0 deletions docs/source/1.0/spec/aws/aws-json-1_1-protocol.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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:

----------------------------------
Expand Down
Loading