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. |
This comment has been minimized.
This comment has been minimized.
| 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/?
There was a problem hiding this comment.
We can keep the handwritten docs in the service dir. It's a little awkward to have handwritten and code generated documentation combined into the same file in my opinion.
Codegen changes would modify the handwritten API.md and the changes would be committed, etc. It seems cleaner to code generate everything.
There was a problem hiding this comment.
I mean keeping them in /services/ but with a different file name. Renaming services/s3/API.md to services/s3/s3.md
There was a problem hiding this comment.
Or some other consistent name, as long as it's not API.md, because you're right, that will cause a clash
| .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.
|
A new generated diff is ready to view. |
This comment has been minimized.
This comment has been minimized.
| /** | ||
| * Maps a service's SDK ID to its handwritten module documentation file in the `resources` dir. | ||
| * The module documentation files MUST be markdown files. | ||
| */ | ||
| private val HAND_WRITTEN_SERVICES_MAP = mapOf( | ||
| "S3" to "S3.md", | ||
| ) |
There was a problem hiding this comment.
Since we have a consistent naming pattern, I don't think we need to manually maintain this list? Can we just check if the .md file exists and render it?
|
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. |
| generateBoilerPlate(ctx), | ||
| ) | ||
| if (handWritten.keys.contains(sdkId)) { | ||
| val handWrittenDocsFile = handWrittenDocsFile(ctx.settings) |
There was a problem hiding this comment.
naming: the function and the value have the same name, handWrittenDocsFile, which can be hard to read. Consider renaming function to getHandWrittenDocsFile
Also nit/style: you can check if the file exists inside getHandWrittenDocsFile and return null if it doesn't.
That would simplify this code section to just: getHandWrittenDocsFile(ctx)?.let { append(it.readText()) }
Affected ArtifactsChanged in size
|
2 participants
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.