Unverified Commit cf466133 authored by John DiSanti's avatar John DiSanti Committed by GitHub
Browse files

Generate service READMEs and fix module descriptions (#766) 

* Generate service readmes and fix module descriptions

* Add missing `moduleDescription` to codegen tests

* Update changelogs

* Add `moduleDescription` to server codegen tests

* Fix event stream allow list in build.gradle.kts

* Type alias and doc comment the manifest customizations
parent 57af50d7

CHANGELOG.md

+8 −0
Original line number Diff line number Diff line 
vNext (Month Day, Year)

=======================



**Breaking Changes**



- :warning: The `rust-codegen` plugin now requires a `moduleDescription` in the *smithy-build.json* file. This

  property goes into the generated *Cargo.toml* file as the package description. (smithy-rs#766)



**New this week**



- Add `RustSettings` to `CodegenContext` (smithy-rs#616, smithy-rs#752)

- Prepare crate manifests for publishing to crates.io (smithy-rs#755)

- Generated *Cargo.toml* files can now be customized (smithy-rs#766)



v0.25.1 (October 11th, 2021)

=========================

aws/SDK_CHANGELOG.md

+3 −0
Original line number Diff line number Diff line 
vNext (Month Day, Year)

=======================



**New this week**



- Prepare crate manifests for publishing to crates.io (smithy-rs#755)

- Add support for IAM Roles for tasks (smithy-rs#765, aws-sdk-rust#123)

- All service crates now have generated README files (smithy-rs#766)



v0.0.20-alpha (October 7, 2021)

===============================

aws/sdk-codegen/build.gradle.kts

+1 −0
Original line number Diff line number Diff line
@@ -22,6 +22,7 @@ val kotestVersion: String by project 
dependencies {

    implementation(project(":codegen"))

    runtimeOnly(project(":aws:rust-runtime"))

    implementation("org.jsoup:jsoup:1.14.3")

    implementation("software.amazon.smithy:smithy-protocol-test-traits:$smithyVersion")

    implementation("software.amazon.smithy:smithy-aws-traits:$smithyVersion")

    testImplementation("org.junit.jupiter:junit-jupiter:5.6.1")

aws/sdk-codegen/src/main/kotlin/software/amazon/smithy/rustsdk/AwsCodegenDecorator.kt

+1 −0
Original line number Diff line number Diff line
@@ -25,6 +25,7 @@ val DECORATORS = listOf( 
    CrateLicenseDecorator(),

    SharedConfigDecorator(),

    AwsPresigningDecorator(),

    AwsReadmeDecorator(),



    // Smithy specific decorators

    RetryConfigDecorator(),

aws/sdk-codegen/src/main/kotlin/software/amazon/smithy/rustsdk/AwsReadmeDecorator.kt

0 → 100644
+81 −0
Original line number Diff line number Diff line 
/*

 * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.

 * SPDX-License-Identifier: Apache-2.0.

 */



package software.amazon.smithy.rustsdk



import org.jsoup.Jsoup

import software.amazon.smithy.model.traits.DocumentationTrait

import software.amazon.smithy.rust.codegen.rustlang.raw

import software.amazon.smithy.rust.codegen.smithy.CodegenContext

import software.amazon.smithy.rust.codegen.smithy.RustCrate

import software.amazon.smithy.rust.codegen.smithy.customize.RustCodegenDecorator

import software.amazon.smithy.rust.codegen.smithy.generators.ManifestCustomizations

import software.amazon.smithy.rust.codegen.util.getTrait



/**

 * Generates a README.md for each service crate for display on crates.io.

 */

class AwsReadmeDecorator : RustCodegenDecorator {

    override val name: String = "AwsReadmeDecorator"

    override val order: Byte = 0



    override fun crateManifestCustomizations(codegenContext: CodegenContext): ManifestCustomizations =

        mapOf("package" to mapOf("readme" to "README.md"))



    override fun extras(codegenContext: CodegenContext, rustCrate: RustCrate) {

        rustCrate.withFile("README.md") { writer ->

            // Strip HTML from the doc trait value. In the future when it's written, we can use our Rustdoc

            // documentation normalization code to convert this to Markdown.

            val description = Jsoup.parse(

                codegenContext.settings.getService(codegenContext.model).getTrait<DocumentationTrait>()?.value ?: ""

            ).text()

            val moduleName = codegenContext.settings.moduleName



            writer.raw(

                """

                # $moduleName



                **Please Note: The SDK is currently released as an alpha and is intended strictly for

                feedback purposes only. Do not use this SDK for production workloads.**



                $description



                ## Getting Started



                > Examples are availble for many services and operations, check out the

                > [examples folder in GitHub](https://github.com/awslabs/aws-sdk-rust/tree/main/sdk/examples).



                The SDK provides one crate per AWS service. You must add [Tokio](https://crates.io/crates/tokio)

                as a dependency within your Rust project to execute asynchronous code. To add `$moduleName` to

                your project, add the following to your **Cargo.toml** file:



                ```toml

                [dependencies]

                aws-config = "${codegenContext.settings.moduleVersion}"

                $moduleName = "${codegenContext.settings.moduleVersion}"

                tokio = { version = "1", features = ["full"] }

                ```



                ## Using the SDK



                Until the SDK is released, we will be adding information about using the SDK to the

                [Guide](https://github.com/awslabs/aws-sdk-rust/blob/main/Guide.md). Feel free to suggest

                additional sections for the guide by opening an issue and describing what you are trying to do.



                ## Getting Help



                * [GitHub discussions](https://github.com/awslabs/aws-sdk-rust/discussions) - For ideas, RFCs & general questions

                * [GitHub issues](https://github.com/awslabs/aws-sdk-rust/issues/new/choose) – For bug reports & feature requests

                * [Generated Docs (latest version)](https://awslabs.github.io/aws-sdk-rust/)

                * [Usage examples](https://github.com/awslabs/aws-sdk-rust/tree/main/sdk/examples)



                ## License



                This project is licensed under the Apache-2.0 License.

                """.trimIndent()

            )

        }

    }

}