Convert HTML to markdown format for Dokka compatiblity

[kggilmer]

Unlike javadoc, Dokka does not support embedded HTML in comments. The Smithy spec specifies that documentation is specified in CommonMark, of which HTML is a subset. In practice, most if not all AWS docs appear to be HTML documents.

When HTML is embedded in Dokka comments, the IDE does not display any content wrapped in tags. The short term solution is to simply remove most common HTML tags from the HTML documentation so that it is visiable to the user. However this destroys formatting and other important information. The better solution is to convert HTML markup into markdown.

From a brief search there seem to be a few JVM libraries that do this. Unsure if they are suitable or a homegrown solution is needed.

Acceptance Criteria: HTML docs are translated into Markdown such that important details and basic formatting are preserved from the HTML.

internal id: 177053427

[kggilmer]

Related:

• Rust: https://github.com/awslabs/smithy-rs/blob/1586d0b0c4f6c785ab6a02c0db49f58deb053a38/aws/sdk-codegen/src/main/kotlin/software/amazon/smithy/rustsdk/AwsReadmeDecorator.kt
• Swift: feat: generate convert html to markdown for generated docs smithy-swift#381

[aajtodd]

https://github.com/aws/smithy-go/blob/main/codegen/smithy-go-codegen/src/main/java/software/amazon/smithy/go/codegen/DocumentationConverter.java