Unverified Commit 4dc75bb2 authored by Zelda Hessler's avatar Zelda Hessler Committed by GitHub
Browse files

fix: in generated docs, convert bare anchor tags to pre (#1019) 

* fix: in generated docs, convert bare anchor tags to pre

* update: CHANGELOG.next.toml

* update: use html transformation instead of regex find/replace

* Update codegen/src/main/kotlin/software/amazon/smithy/rust/codegen/rustlang/RustWriter.kt
parent 9856714a

CHANGELOG.next.toml

+12 −0
Original line number Diff line number Diff line
@@ -11,6 +11,18 @@ 
# meta = { "breaking" = false, "tada" = false, "bug" = false }

# author = "rcoh"



[[aws-sdk-rust]]

message = "Generated docs should no longer contain links that don't go anywhere"

references = ["aws-sdk-rust#357"]

meta = { "breaking" = false, "tada" = false, "bug" = true }

author = "Velfi"



[[smithy-rs]]

message = "Generated docs will convert `<a>` tags with no `href` attribute to `<pre>` tags"

references = ["aws-sdk-rust#357"]

meta = { "breaking" = false, "tada" = false, "bug" = true }

author = "Velfi"



[[smithy-rs]]

message = "Made fluent operation structs cloneable"

references = ["aws-sdk-rust#254"]

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(kotlin("stdlib-jdk8"))

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

    api("software.amazon.smithy:smithy-codegen-core:$smithyVersion")

    api("com.moandjiezana.toml:toml4j:0.7.2")

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

codegen/src/main/kotlin/software/amazon/smithy/rust/codegen/rustlang/RustWriter.kt

+26 −1
Original line number Diff line number Diff line
@@ -6,6 +6,8 @@ 
package software.amazon.smithy.rust.codegen.rustlang



import org.intellij.lang.annotations.Language

import org.jsoup.Jsoup

import org.jsoup.nodes.Element

import software.amazon.smithy.codegen.core.CodegenException

import software.amazon.smithy.codegen.core.Symbol

import software.amazon.smithy.codegen.core.writer.CodegenWriter
@@ -212,7 +214,7 @@ fun <T : CodeWriter> T.documentShape(shape: Shape, model: Model, autoSuppressMis 
    when (docTrait?.value?.isNotBlank()) {

        // If docs are modeled, then place them on the code generated shape

        true -> {

            this.docs(escape(docTrait.value))

            this.docs(normalizeHtml(escape(docTrait.value)))

            note?.also {

                // Add a blank line between the docs and the note to visually differentiate

                write("///")
@@ -260,6 +262,29 @@ fun <T : CodeWriter> T.docs(text: String, vararg args: Any, newlinePrefix: Strin 
/** Escape the [expressionStart] character to avoid problems during formatting */

fun CodeWriter.escape(text: String): String = text.replace("$expressionStart", "$expressionStart$expressionStart")



/** Parse input as HTML and normalize it */

fun normalizeHtml(input: String): String {

    val doc = Jsoup.parse(input)

    doc.body().apply {

        normalizeAnchors() // Convert anchor tags missing href attribute into pre tags

    }



    return doc.body().html()

}



private fun Element.normalizeAnchors() {

    getElementsByTag("a").forEach {

        val link = it.attr("href")

        if (link.isBlank()) {

            it.changeInto("code")

        }

    }

}



private fun Element.changeInto(tagName: String) {

    replaceWith(Element(tagName).also { elem -> elem.appendChildren(childNodesCopy()) })

}



/**

 * Write _exactly_ the text as written into the code writer without newlines or formatting

 */