Unverified Commit 5c0bfa4f authored by Russell Cohen's avatar Russell Cohen Committed by GitHub
Browse files

Generate Crate Documentation (#93) 

* Generate Crate Documentation

This commit utilizes the documentation trait attached to the relevant service shape to generate crate-level documentation for services.

* Test fixes

* Don't upload integration test docs
parent 883fc057

.github/workflows/ci.yaml

+0 −1
Original line number Diff line number Diff line
@@ -95,7 +95,6 @@ jobs: 
        path: |

          codegen-test/build/smithyprojections/codegen-test/*/rust-codegen/

          codegen-test/build/smithyprojections/codegen-test/Cargo.toml

          codegen-test/build/smithyprojections/codegen-test/target/doc

  runtime-tests:

    name: Rust runtime tests

    runs-on: ubuntu-latest

codegen-test/build.gradle.kts

+5 −5
Original line number Diff line number Diff line
@@ -98,7 +98,7 @@ task("generateCargoWorkspace") { 
}



tasks["smithyBuildJar"].dependsOn("generateSmithyBuild")

tasks["build"].finalizedBy("generateCargoWorkspace")

tasks["assemble"].finalizedBy("generateCargoWorkspace")





tasks.register<Exec>("cargoCheck") {
@@ -106,7 +106,7 @@ tasks.register<Exec>("cargoCheck") { 
    // disallow warnings

    environment("RUSTFLAGS", "-D warnings")

    commandLine("cargo", "check")

    dependsOn("build")

    dependsOn("assemble")

}



tasks.register<Exec>("cargoTest") {
@@ -114,7 +114,7 @@ tasks.register<Exec>("cargoTest") { 
    // disallow warnings

    environment("RUSTFLAGS", "-D warnings")

    commandLine("cargo", "test")

    dependsOn("build")

    dependsOn("assemble")

}



tasks.register<Exec>("cargoDocs") {
@@ -122,7 +122,7 @@ tasks.register<Exec>("cargoDocs") { 
    // disallow warnings

    environment("RUSTFLAGS", "-D warnings")

    commandLine("cargo", "doc", "--no-deps")

    dependsOn("build")

    dependsOn("assemble")

}



tasks.register<Exec>("cargoClippy") {
@@ -130,7 +130,7 @@ tasks.register<Exec>("cargoClippy") { 
    // disallow warnings

    environment("RUSTFLAGS", "-D warnings")

    commandLine("cargo", "clippy")

    dependsOn("build")

    dependsOn("assemble")

}



tasks["test"].finalizedBy("cargoCheck", "cargoClippy", "cargoTest", "cargoDocs")

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

+9 −3
Original line number Diff line number Diff line
@@ -129,9 +129,9 @@ fun <T : CodeWriter> T.documentShape(shape: Shape, model: Model): T { 
 *    - Tabs are replaced with spaces

 *    - Empty newlines are removed

 */

fun <T : CodeWriter> T.docs(text: String, vararg args: Any) {

fun <T : CodeWriter> T.docs(text: String, vararg args: Any, newlinePrefix: String = "/// "): T {

    pushState()

    setNewlinePrefix("/// ")

    setNewlinePrefix(newlinePrefix)

    // TODO: Smithy updates should remove the need for a number of these changes

    val cleaned = text.lines()

        // We need to filter out blank lines—an empty line causes the markdown parser to interpret the subsequent
@@ -143,6 +143,7 @@ fun <T : CodeWriter> T.docs(text: String, vararg args: Any) { 
        }

    write(cleaned, *args)

    popState()

    return this

}



/** Escape the [expressionStart] character to avoid problems during formatting */
@@ -162,6 +163,11 @@ class RustWriter private constructor( 
    private val printWarning: Boolean = true

) :

    CodegenWriter<RustWriter, UseDeclarations>(null, UseDeclarations(namespace)) {

    private var headerDocs: String? = null

    fun setHeaderDocs(docs: String) {

        headerDocs = RustWriter("", "", printWarning = false).docs(docs, newlinePrefix = "//! ").toString()

    }



    companion object {

        fun root() = forModule(null)

        fun forModule(module: String?): RustWriter = if (module == null) {
@@ -265,7 +271,7 @@ class RustWriter private constructor( 
            "$commentCharacter Code generated by software.amazon.smithy.rust.codegen.smithy-rs. DO NOT EDIT."

        } else ""

        val useDecls = importContainer.toString()

        return "$header\n$useDecls\n$contents\n"

        return "${headerDocs ?: ""}\n$header\n$useDecls\n$contents\n"

    }



    fun format(r: Any): String {

codegen/src/main/kotlin/software/amazon/smithy/rust/codegen/smithy/CodegenDelegator.kt

+2 −2
Original line number Diff line number Diff line
@@ -48,7 +48,7 @@ fun CodegenWriterDelegator<RustWriter>.finalize(settings: RustSettings) { 
        val cargoToml = CargoTomlGenerator(

            settings,

            it,

            cargoDependencies

            cargoDependencies,

        )

        cargoToml.render()

    }
@@ -57,7 +57,7 @@ fun CodegenWriterDelegator<RustWriter>.finalize(settings: RustSettings) { 
        val modules = includedModules.map { moduleName ->

            RustModule.default(moduleName, PublicModules.contains(moduleName))

        }

        LibRsGenerator(modules).render(writer)

        LibRsGenerator(settings.moduleDescription, modules).render(writer)

    }

    flushWriters()

}

codegen/src/main/kotlin/software/amazon/smithy/rust/codegen/smithy/RustSettings.kt

+11 −5
Original line number Diff line number Diff line
@@ -13,6 +13,7 @@ import software.amazon.smithy.model.node.StringNode 
import software.amazon.smithy.model.shapes.ServiceShape

import software.amazon.smithy.model.shapes.Shape

import software.amazon.smithy.model.shapes.ShapeId

import software.amazon.smithy.model.traits.DocumentationTrait

import java.util.Optional

import java.util.logging.Logger

import kotlin.streams.toList
@@ -46,11 +47,11 @@ class RustSettings( 
    val service: ShapeId,

    val moduleName: String,

    val moduleVersion: String,

    val moduleDescription: String = "",

    val moduleAuthors: List<String> = listOf("TODO@todo.com"),

    val runtimeConfig: RuntimeConfig,

    val codegenConfig: CodegenConfig,

    val build: BuildSettings

    val build: BuildSettings,

    private val model: Model

) {



    /**
@@ -66,6 +67,12 @@ class RustSettings( 
            .orElseThrow { CodegenException("Shape is not a service: $service") }

    }



    val moduleDescription: String

        get() {

            val service = getService(model)

            return service.getTrait(DocumentationTrait::class.java).map { it.value }.orElse(moduleName)

        }



    companion object {

        private val LOGGER: Logger = Logger.getLogger(RustSettings::class.java.name)
@@ -95,7 +102,6 @@ class RustSettings( 


            val moduleName = config.expectStringMember(MODULE_NAME).value

            val version = config.expectStringMember(MODULE_VERSION).value

            val desc = config.getStringMemberOrDefault(MODULE_DESCRIPTION, "$moduleName client")

            val build = config.getObjectMember(BUILD_SETTINGS)

            val runtimeConfig = config.getObjectMember(RUNTIME_CONFIG)

            val codegenSettings = config.getObjectMember(CODEGEN_SETTINGS)
@@ -103,10 +109,10 @@ class RustSettings( 
                service,

                moduleName,

                version,

                desc,

                runtimeConfig = RuntimeConfig.fromNode(runtimeConfig),

                codegenConfig = CodegenConfig.fromNode(codegenSettings),

                build = BuildSettings.fromNode(build)

                build = BuildSettings.fromNode(build),

                model = model

            )

        }