Skip to content

misc: upgrade to Dokka 2.0.0 #1284

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 24 commits into from
Jun 13, 2025
Merged

misc: upgrade to Dokka 2.0.0 #1284

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
06214ac
Docs are getting generated
lauzadis Dec 11, 2024
4295247
Correct dokka-convention plugin
lauzadis Dec 11, 2024
21694f3
ktlint
lauzadis Dec 11, 2024
1ef6ce1
revert README change
lauzadis Dec 11, 2024
5b3f1e1
Disable V2 helpers
lauzadis Dec 11, 2024
f49cc50
Combine config blocks
lauzadis Dec 11, 2024
30becbb
Remove fileLayout config, does not seem necessary anymore
lauzadis Dec 11, 2024
dfe21bf
Changelog
lauzadis Dec 11, 2024
d2f7d17
Merge branch 'main' of github.com:smithy-lang/smithy-kotlin into try-…
lauzadis Jan 23, 2025
4fee104
Upgrade to Dokka 2.0.0
lauzadis Jan 23, 2025
7e2cdbf
merge branch 'main' of github.com:smithy-lang/smithy-kotlin into try-…
lauzadis Jan 24, 2025
ff216a1
kotlinOptions -> compilerOptions
lauzadis Jan 24, 2025
ead3683
Bump to latest versions
lauzadis Jan 24, 2025
865e4a4
Style changes
lauzadis Jan 24, 2025
5ad6cb4
Delete changelog
lauzadis Jan 24, 2025
dc115f3
Apply same fixes as aws-sdk-kotlin
lauzadis May 15, 2025
4e688fa
Merge branch 'main' of github.com:smithy-lang/smithy-kotlin into try-…
lauzadis May 15, 2025
779a749
Fix analytics test, add template back
lauzadis May 15, 2025
d0cc97c
CI
lauzadis May 15, 2025
99cbbe5
Merge branch 'main' of github.com:smithy-lang/smithy-kotlin into try-…
lauzadis Jun 10, 2025
cc6e0e5
Remove search button
lauzadis Jun 10, 2025
185c9d8
Remove /build exclusion
lauzadis Jun 11, 2025
5d80218
revert: Remove /build exclusion
lauzadis Jun 11, 2025
5d9320b
Merge branch 'main' into try-dokka-2
lauzadis Jun 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changes/50a9ce20-c4d7-4952-8fad-f9ffb38c9259.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{
"id": "50a9ce20-c4d7-4952-8fad-f9ffb38c9259",
"type": "misc",
"description": "Upgrade to Dokka 2.0.0"
}
2 changes: 1 addition & 1 deletion .editorconfig
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,4 +9,4 @@ ktlint_standard_backing-property-naming = disabled
# enable trailing commas per JetBrains recommendation
# (https://kotlinlang.org/docs/coding-conventions.html#trailing-commas)
ij_kotlin_allow_trailing_comma_on_call_site = true
ij_kotlin_allow_trailing_comma = true
ij_kotlin_allow_trailing_comma = true
62 changes: 14 additions & 48 deletions build.gradle.kts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,13 +18,13 @@ buildscript {
}

plugins {
alias(libs.plugins.dokka)
`dokka-convention`
alias(libs.plugins.kotlinx.binary.compatibility.validator)
alias(libs.plugins.aws.kotlin.repo.tools.artifactsizemetrics)
// ensure the correct version of KGP ends up on our buildscript classpath
// since build-plugins also has <some> version in its dependency closure
alias(libs.plugins.kotlin.multiplatform) apply false
alias(libs.plugins.kotlin.jvm) apply false
alias(libs.plugins.aws.kotlin.repo.tools.artifactsizemetrics)
id(libs.plugins.kotlin.multiplatform.get().pluginId) apply false
id(libs.plugins.kotlin.jvm.get().pluginId) apply false
}

artifactSizeMetrics {
Expand All @@ -40,35 +40,9 @@ val testJavaVersion = typedProp<String>("test.java.version")?.let {
}

allprojects {
tasks.withType<org.jetbrains.dokka.gradle.AbstractDokkaTask>().configureEach {
val sdkVersion: String by project
moduleVersion.set(sdkVersion)

val year = java.time.LocalDate.now().year
val pluginConfigMap = mapOf(
"org.jetbrains.dokka.base.DokkaBase" to """
{
"customStyleSheets": [
"${rootProject.file("docs/dokka-presets/css/logo-styles.css")}",
"${rootProject.file("docs/dokka-presets/css/aws-styles.css")}"
],
"customAssets": [
"${rootProject.file("docs/dokka-presets/assets/logo-icon.svg")}",
"${rootProject.file("docs/dokka-presets/assets/aws_logo_white_59x35.png")}",
"${rootProject.file("docs/dokka-presets/scripts/accessibility.js")}"
],
"footerMessage": "© $year, Amazon Web Services, Inc. or its affiliates. All rights reserved.",
"separateInheritedMembers" : true,
"templatesDir": "${rootProject.file("docs/dokka-presets/templates")}"
}
""",
)
pluginsMapConfiguration.set(pluginConfigMap)
}

if (rootProject.typedProp<Boolean>("kotlinWarningsAsErrors") == true) {
tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile> {
kotlinOptions.allWarningsAsErrors = true
compilerOptions.allWarningsAsErrors = true
}
}

Expand All @@ -90,27 +64,18 @@ allprojects {
}

// configure the root multimodule docs
tasks.dokkaHtmlMultiModule.configure {
dokka {
moduleName.set("Smithy Kotlin")

// Output subprojects' docs to <docs-base>/project-name/* instead of <docs-base>/path/to/project-name/*
// This is especially important for inter-repo linking (e.g., via externalDocumentationLink) because the
// package-list doesn't contain enough project path information to indicate where modules' documentation are
// located.
fileLayout.set { parent, child ->
parent.outputDirectory.dir(child.moduleName)
Comment on lines -96 to -101
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does dokka handle this now or is the layout going to change?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This didn't seem to be necessary anymore in my testing. It was an old bit of code, might have been fixed a long time ago or just now in Dokka 2.0.0

dokkaPublications.html {
includes.from(
rootProject.file("docs/dokka-presets/README.md"),
)
}
}

includes.from(
// NOTE: these get concatenated
rootProject.file("docs/dokka-presets/README.md"),
)

val excludeFromDocumentation = listOf(
project(":runtime:testing"),
project(":runtime:smithy-test"),
)
removeChildTasks(excludeFromDocumentation)
dependencies {
dokka(project(":runtime"))
}
Comment on lines +77 to 79
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why do we need this now?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you mean the dokka(project(":runtime"))? This is how you aggregate multi-module documentation in Dokka 2: https://kotlinlang.org/docs/dokka-migration.html#update-documentation-aggregation-in-multi-module-projects


// Publishing
Expand All @@ -121,6 +86,7 @@ val lintPaths = listOf(
"**/*.{kt,kts}",
"!**/generated-src/**",
"!**/smithyprojections/**",
"!**/build/**",
)
Comment on lines 86 to 90
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Question: I agree we shouldn't be linting files in the build dir but I'm curious why it wasn't an issue before now. Is the upgraded version of Dokka now generating .kt files in build?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was running into an issue but it seems unreproducible now, I'll remove this

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ran into the error again 😮‍💨, it's caused by some DSL accessors that are auto-generated

/Users/lauzmata/smithy-kotlin/buildSrc/build/generated-sources/kotlin-dsl-accessors/kotlin/gradle/kotlin/dsl/accessors/_15f47bddd2e04434c8db9f87ceea0581/DokkaHtmlGeneratorRuntimeConfigurationAccessors.kt:204:44: Function name should start with a lowercase letter (except factory methods) and use camel case (cannot be auto-corrected) (standard:function-naming)
/Users/lauzmata/smithy-kotlin/buildSrc/build/generated-sources/kotlin-dsl-accessors/kotlin/gradle/kotlin/dsl/accessors/_15f47bddd2e04434c8db9f87ceea0581/DokkaHtmlGeneratorRuntimeConfigurationAccessors.kt:32:10: Package name must not contain underscore (cannot be auto-corrected) (standard:package-name)

Summary error count (descending) by rule:
  standard:function-naming: 274
  standard:package-name: 102
  standard:class-naming: 12


configureLinting(lintPaths)
Expand Down
13 changes: 13 additions & 0 deletions buildSrc/build.gradle.kts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
plugins {
`kotlin-dsl`
}

repositories {
mavenCentral()
gradlePluginPortal()
}

dependencies {
implementation(libs.dokka.gradle.plugin)
implementation(libs.kotlin.gradle.plugin)
}
9 changes: 9 additions & 0 deletions buildSrc/settings.gradle.kts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
rootProject.name = "buildSrc"

dependencyResolutionManagement {
versionCatalogs {
create("libs") {
from(files("../gradle/libs.versions.toml"))
}
}
}
30 changes: 30 additions & 0 deletions buildSrc/src/main/kotlin/dokka-convention.gradle.kts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
import kotlin.text.set
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Question: I like the idea of refactoring this out of the main build file. How much more work would it be to move it all the way out into aws-kotlin-repo-tools so that we had less duplication?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's possible to consume a conventions plugin (one defined in aws-kotlin-repo-tools) from another conventions plugin (one defined in smithy-kotlin).

We'd still need to have this dokka-convention plugin defined in smithy-kotlin and keep the dependencies { } block which is repo-specific.

I don't think it's worth commonizing the 20 lines of config that we have here at the moment

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why? What about this Dokka configuration is unique to smithy-kotlin?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Most of this is not unique to smithy-kotlin. This is:

dependencies {
    dokkaPlugin(project(":dokka-smithy"))
}

The rest of the file could be commonized but then we'd still need a convention plugin defined in each repository

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

aws-sdk-kotlin has an additional custom asset navigation-loader.js which would also need to be manually defined / deviated from the proposed commonized plugin. I think it's fine to leave them separate for now


plugins {
id("org.jetbrains.dokka")
}

dokka {
val sdkVersion: String by project
moduleVersion.set(sdkVersion)

pluginsConfiguration.html {
customStyleSheets.from(
rootProject.file("docs/dokka-presets/css/aws-styles.css"),
)

customAssets.from(
rootProject.file("docs/dokka-presets/assets/logo-icon.svg"),
rootProject.file("docs/dokka-presets/scripts/accessibility.js"),
)

templatesDir.set(rootProject.file("docs/dokka-presets/templates"))

footerMessage.set("© ${java.time.LocalDate.now().year}, Amazon Web Services, Inc. or its affiliates. All rights reserved.")
separateInheritedMembers.set(true)
}
}

dependencies {
dokkaPlugin(project(":dokka-smithy"))
}
2 changes: 1 addition & 1 deletion codegen/smithy-aws-kotlin-codegen/build.gradle.kts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ import org.jetbrains.kotlin.gradle.dsl.JvmTarget
import org.jetbrains.kotlin.gradle.tasks.KotlinCompile

plugins {
alias(libs.plugins.kotlin.jvm)
id(libs.plugins.kotlin.jvm.get().pluginId)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Question: Why did this need to change? (applies in multiple build files)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was getting an error:

* Where:
Build file '/Users/lauzmata/smithy-kotlin/build.gradle.kts' line: 20

* What went wrong:
Error resolving plugin [id: 'org.jetbrains.kotlin.multiplatform', version: '2.1.0', apply: false]
> The request for this plugin could not be satisfied because the plugin is already on the classpath with an unknown version, so compatibility cannot be checked.

and followed this suggestion

jacoco
`maven-publish`
}
Expand Down
2 changes: 1 addition & 1 deletion codegen/smithy-kotlin-codegen-testutils/build.gradle.kts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ import org.jetbrains.kotlin.gradle.dsl.JvmTarget
import org.jetbrains.kotlin.gradle.tasks.KotlinCompile

plugins {
alias(libs.plugins.kotlin.jvm)
id(libs.plugins.kotlin.jvm.get().pluginId)
jacoco
`maven-publish`
}
Expand Down
2 changes: 1 addition & 1 deletion codegen/smithy-kotlin-codegen/build.gradle.kts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ import org.jetbrains.kotlin.gradle.dsl.JvmTarget
import org.jetbrains.kotlin.gradle.tasks.KotlinCompile

plugins {
alias(libs.plugins.kotlin.jvm)
id(libs.plugins.kotlin.jvm.get().pluginId)
jacoco
`maven-publish`
}
Expand Down
Binary file removed docs/dokka-presets/assets/aws_logo_white_59x35.png
View file
Open in desktop
Binary file not shown.
16 changes: 1 addition & 15 deletions docs/dokka-presets/assets/logo-icon.svg
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
107 changes: 46 additions & 61 deletions docs/dokka-presets/css/aws-styles.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,45 +4,29 @@
*/

:root {
--aws-color-dark: #232f3e;
--horizontal-spacing-for-content: 16px;
--default-font-family: JetBrains Sans, Inter, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI,Roboto, Oxygen, Ubuntu,Cantarell, Droid Sans, Helvetica Neue, Arial, sans-serif;
--color-background-nav: #232f3e;
--dokka-logo-height: 60px;
--dokka-logo-width: 90px;
}

.menu-toggle {
background: none;
}

.menu-toggle:focus {
outline: 2px solid #fff; /* White outline */
outline-offset: 2px; /* Space between the outline and the button */
}

#pages-search:focus {
outline: revert;
}

/* copied from Dokka except for background-color attribute */
.navigation {
display: flex;
justify-content: space-between;

color: #fff;
background-color: var(--aws-color-dark);
font-family: var(--default-font-family);
letter-spacing: -0.1px;

/* Reset margin and use padding for border */
margin-left: 0;
margin-right: 0;
padding: 10px var(--horizontal-spacing-for-content);

z-index: 4;
.skip-to-content {
position: absolute; /* Remove from normal flow */
top: 0; /* Position off-screen */
left: 0;
width: 1px;
height: 1px;
overflow: hidden;
opacity: 0;
z-index: -1; /* Ensure it's not visible */
}

/* Styles for section tabs like "Types" and "Functions" */
.section-tab:focus, .section-tab:active {
outline: 2px solid var(--active-tab-border-color); /* The color appears unresolved, but it is defined in Dokka style sheets */
.skip-to-content:focus,
.skip-to-content:active {
position: static; /* Restore to normal flow when focused */
width: auto;
height: auto;
opacity: 1;
z-index: 999; /* Ensure it's on top */
}

/*
Expand All @@ -55,44 +39,45 @@
.symbol {
overflow-wrap: break-word;
}

.keyValue {
display: block;
}

/*
Disable the playground run button for generated samples
https://github.com/Kotlin/dokka/issues/3041
*/
div .compiler-info, .fold-button, .run-button {
display: none;
/* FIXME Taken from Dokka mainline. Remove these styles once Dokka 2.1.0 is released. */
.toc--skip-link {
background-color: #458cff;
color: #fff;
font: 400 13px/24px Inter, system-ui, -apple-system, Segoe UI, Roboto, Ubuntu, Cantarell, Noto Sans, sans-serif, BlinkMacSystemFont, Oxygen, Droid Sans, Helvetica Neue, Arial;
margin-top: 36px;
padding: 1px;
position: absolute;
z-index: 100;
}

.skip-to-content {
width: 1px;
height: 1px;
overflow: hidden;
opacity: 0;
.toc--skip-link:not(:focus) {
overflow: hidden !important;
clip: rect(1px, 1px, 1px, 1px) !important;
border: 0 !important;
height: 1px !important;
padding: 0 !important;
width: 1px !important;
}

.skip-to-content:focus,
.skip-to-content:active {
width: auto;
height: auto;
opacity: 1;
z-index: 999; /* Ensure the skip link is on top of other content */
.toc--skip-link:focus {
outline: 4px solid rgb(48, 127, 255, 0.5);
outline-offset: 0;
}

.sidebar > .toc--skip-link {
margin-top: 0;
}

.aws-toggle-content-btn {
font-size: 24px;
background: none;
border: none;
cursor: pointer;
padding: 8px;
.toc--part_hidden > .toc--row > .toc--button ~ .toc--skip-link {
display: none;
}

@media (max-width: 550px) {
.content[data-togglable] {
@media (max-width: 899px) {
.toc--skip-link {
display: none;
}
}
39 changes: 0 additions & 39 deletions docs/dokka-presets/css/logo-styles.css
View file
Open in desktop

This file was deleted.

Loading
Loading