Generate service READMEs and fix module descriptions #766
Conversation
| writer.raw( | ||
| """ | ||
| # $moduleName | ||
|
|
||
| **Please Note: The SDK is currently released as an alpha and is intended strictly for |
There was a problem hiding this comment.
Long term, I think we should probably generate the entire top-level README.md file in aws-sdk-rust so that it's kept in sync with this one. I omitted a few sections in this README since I didn't think all of them made sense in this context.
For now, we will need to remember to update both READMEs, unless you think the investment is worth it now?
There was a problem hiding this comment.
maybe we can put an HTML comment in both noting that they both need to be updated
There was a problem hiding this comment.
I'm skeptical anyone would actually see that when updating one of the READMEs unless they were updating the entire README rather than just a part of it.
There was a problem hiding this comment.
Filed #770 to track this.
| AwsService( | ||
| service = service.id.toString(), | ||
| module = sdkId, | ||
| moduleDescription = "AWS SDK for $title", |
There was a problem hiding this comment.
Examples for this value:
- AWS SDK for Amazon Simple Storage Service
- AWS SDK for AWS Identity and Access Management
- AWS SDK for Amazon DynamoDB
I think I would prefer to it to be "AWS SDK for S3", but I'm not sure if there's a reliable model attribute for that. One would think the Service sdkId would work, but that value doesn't look great for a number of services.
|
I'm not sure why these changes would cause the errors CI is seeing for the generated transcribestreaming crate. Edit: It was caused by the event stream allow list being broken by a rename in build.gradle.kts. |
| writer.raw( | ||
| """ | ||
| # $moduleName | ||
|
|
||
| **Please Note: The SDK is currently released as an alpha and is intended strictly for |
There was a problem hiding this comment.
maybe we can put an HTML comment in both noting that they both need to be updated
| fun finalize( | ||
| settings: RustSettings, | ||
| model: Model, | ||
| manifestCustomizations: Map<String, Any?>, |
There was a problem hiding this comment.
add a comment about what this map is since it's the fairly opaque str->any?
There was a problem hiding this comment.
Opted to type alias it and add a large doc comment to the alias.
| @@ -38,7 +41,8 @@ class CargoTomlGenerator( | |||
| "dev-dependencies" to dependencies.filter { it.scope == DependencyScope.Dev } | |||
| .associate { it.name to it.toMap() }, | |||
| "features" to cargoFeatures.toMap() | |||
| ) | |||
| ).deepMergeWith(manifestCustomizations) | |||
There was a problem hiding this comment.
do we need to do anything to ensure deterministic ordering?
There was a problem hiding this comment.
The decorator order should be sufficient for this.
| private val modules: List<RustModule>, | ||
| private val customizations: List<LibRsCustomization> | ||
| ) { | ||
| fun render(writer: RustWriter) { | ||
| writer.first { | ||
| customizations.forEach { it.section(LibRsSection.Attributes)(this) } | ||
|
|
||
| val libraryDocs = settings.getService(model).getTrait<DocumentationTrait>()?.value ?: settings.moduleName |
There was a problem hiding this comment.
I'd probably lean towards being more explicit here and having LibRsGenerator accept a service, but fine either way. Using the doc trait directly here makes it a little trickier to customize (although I guess we could always do it as a model customization?
I'm just imagining how this will work when we want to start rendering examples in here
There was a problem hiding this comment.
We can easily add a section (similar to the attributes section above) for rendering examples.
Description
Testing
Checklist
CHANGELOG.mdaws/SDK_CHANGELOG.mdif applicableBy submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.