Skip to content

feat: api ref doc sidebar optimization #1599

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.

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

Open
wants to merge 7 commits into
base: main
Choose a base branch
from

Conversation

xinsong-cui
Copy link
Contributor

Issue #

Description of changes

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

@xinsong-cui xinsong-cui changed the title Api ref doc sidebar optimization feat: api ref doc sidebar optimization May 16, 2025
Copy link

A new generated diff is ready to view.

  • No codegen difference in the AWS SDK

Copy link

A new generated diff is ready to view.

  • No codegen difference in the AWS SDK

This comment has been minimized.

build.gradle.kts Outdated
Comment on lines 138 to 140
dokkaOutputDir.listFiles { file ->
file.isDirectory && file.resolve("navigation.html").exists()
}?.forEach { moduleDir ->
Copy link
Member

Choose a reason for hiding this comment

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

There should only be one navigation.html file (in the root of dokkaOutputDir) since we prune the duplicate navigation.html files during our 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.

Do we still want to prune them? Now we are trimming and using these navigations

Copy link
Member

Choose a reason for hiding this comment

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

I didn't realize your navigation loader would use each module's navigation.html. Ok, that will work but we'll need to update our build process to not remove duplicate files (and make sure the docs artifact size doesn't increase significantly)

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Yep, I'll remove that. I did a quick estimation, the doc size should only increased by 300 - 400 MB

build.gradle.kts Outdated
Comment on lines 190 to 199
dokkaOutputDir.walkTopDown()
.filter { it.isFile && it.name.endsWith(".html") }
.forEach { file ->
val updatedContent = file.readLines().filterNot { line ->
line.contains("""scripts/navigation-loader.js""")
}.joinToString("\n")

file.writeText(updatedContent)
}
}
Copy link
Member

Choose a reason for hiding this comment

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

Instead of replacing the HTML content of every file, could we just create our own file navigation-loader.js and add it as a customAsset? Would that override Dokka's default navigation loader script? It seems like a simpler solution

Copy link
Contributor Author

Choose a reason for hiding this comment

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

No I don't think it will override Dokka's loader. The file from customAsset will be put into images folder like images/navigation-loader.js
The Dokka's own navigation-loader is in scripts folders. So both files will be in the generated html.

Copy link
Member

Choose a reason for hiding this comment

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

Oh ok, I see that here: https://github.com/Kotlin/dokka/blob/540fe084aadac0edb333350210ee22ee9901a3de/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/renderers/html/htmlPreprocessors.kt#L37

It sounds like a good feature request to Dokka if you can open one, but we can work around it for this PR

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Sounds good, I can open a request to Dokka

Copy link

A new generated diff is ready to view.

  • No codegen difference in the AWS SDK

This comment has been minimized.

Copy link

A new generated diff is ready to view.

  • No codegen difference in the AWS SDK

This comment has been minimized.

Copy link

A new generated diff is ready to view.

  • No codegen difference in the AWS SDK

This comment has been minimized.

Copy link
Contributor

@0marperez 0marperez left a comment

Choose a reason for hiding this comment

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

Should we do this for smithy-kotlin as well? The navigation sidebar isn't troublesome but for consistency it would be nice to do the same.

@xinsong-cui
Copy link
Contributor Author

xinsong-cui commented May 19, 2025

Should we do this for smithy-kotlin as well? The navigation sidebar isn't troublesome but for consistency it would be nice to do the same.

Yeah, I agree we should keep consistency. I am open to do for smithy-kotlin.

@xinsong-cui xinsong-cui marked this pull request as ready for review May 19, 2025 18:17
@xinsong-cui xinsong-cui requested a review from a team as a code owner May 19, 2025 18:17
Copy link

Copy link

A new generated diff is ready to view.

  • No codegen difference in the AWS SDK

Copy link

Affected Artifacts

No artifacts changed size

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants