feat: link api ref docs to examples #1550
Conversation
0marperez
added
the
no-changelog
|
A new generated diff is ready to view. |
This comment has been minimized.
This comment has been minimized.
|
|
A new generated diff is ready to view. |
Affected ArtifactsNo artifacts changed size |
| import software.amazon.smithy.model.traits.TitleTrait | ||
|
|
||
| /** | ||
| * Maps a services SKD ID to its code examples |
There was a problem hiding this comment.
nit/grammar: service's
typo: SDK
| ) | ||
|
|
||
| /** | ||
| * Maps a services SKD ID to its handwritten module documentation file in the `resources` dir. |
| } | ||
|
|
||
| private fun generateBoilerPlate(ctx: CodegenContext) = buildString { | ||
| // Title must me "Module" followed by the exact module name or dokka won't render it |
|
|
||
| private fun generateCodeExamplesDocs(sdkId: String) = buildString { | ||
| appendLine("## Code Examples") | ||
| appendLine("To see full code examples, see the $sdkId examples in the AWS Code Library. See ${codeExamples[sdkId]}") |
There was a problem hiding this comment.
"AWS Code Library" -> "AWS code example library"
https://docs.aws.amazon.com/code-library/latest/ug/what-is-code-library.html
| private fun generateHandWrittenDocs(sdkId: String): String = object {} | ||
| .javaClass | ||
| .classLoader | ||
| .getResourceAsStream("aws/sdk/kotlin/codegen/moduledocumentation/${handWritten[sdkId]}") |
There was a problem hiding this comment.
I didn't think we'd need to make a new directory for this, can't we keep the handwritten service docs in /services/?
| .getResourceAsStream("aws/sdk/kotlin/codegen/moduledocumentation/${handWritten[sdkId]}") | ||
| ?.bufferedReader() | ||
| ?.readText() | ||
| ?: throw Exception("Unable to read from file ${handWritten[sdkId]}") |
There was a problem hiding this comment.
Throw a more specific exception here
| /** | ||
| * Maps a services SKD ID to its code examples | ||
| */ | ||
| private val currentCodeExamplesServices = mapOf( |
There was a problem hiding this comment.
naming: top-level values should be in SCREAMING_SNAKE_CASE. Also "current" is implied.
Something like CODE_EXAMPLES_SERVICES_MAP
| * Maps a services SKD ID to its handwritten module documentation file in the `resources` dir. | ||
| * The module documentation files MUST be markdown files. | ||
| */ | ||
| private val currentHandWrittenServices = mapOf( |
There was a problem hiding this comment.
Same comment here. "current" is implied. HAND_WRITTEN_SERVICES_MAP
| if (handWritten.keys.contains(sdkId)) { | ||
| append( | ||
| generateHandWrittenDocs(sdkId), | ||
| ) | ||
| } |
There was a problem hiding this comment.
I think we want our hand-written content to appear above links to the code examples.
|
|
||
| private fun generateCodeExamplesDocs(sdkId: String) = buildString { | ||
| appendLine("## Code Examples") | ||
| appendLine("To see full code examples, see the $sdkId examples in the AWS Code Library. See ${codeExamples[sdkId]}") |
There was a problem hiding this comment.
"see the $sdkId examples"
I think we should be using the value from the TitleTrait rather than the sdkId
TitleTrait: Provides a human-readable proper noun title to services and resources.
Issue #
N/A
Description of changes
Module documentation is now handled by an integration. It handles links to code examples and hand written documentation
By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.