diff --git a/build.gradle.kts b/build.gradle.kts index 8195f52..2b23a41 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -22,7 +22,7 @@ plugins { dependencies { // List the 'library' projects dokka(projects.renderer) - dokka(projects.dokkatooMkdocs) + dokka(projects.dokkaMkdocs) } // region Check the users of the project didn't forget to rename the group diff --git a/dokka-mkdocs/README.md b/dokka-mkdocs/README.md index 3ea976b..c8ba2c5 100644 --- a/dokka-mkdocs/README.md +++ b/dokka-mkdocs/README.md @@ -20,7 +20,7 @@ dependencies { } ``` -Add each project that you want to document in the `dependencies {}` block. Each project mentioned in that way must have the Dokkatoo plugin applied. +Add each project that you want to document in the `dependencies {}` block. Each project mentioned in that way must have the Dokka plugin applied. Add the directory in which you created the project in the `settings.gradle.kts` file: ```kotlin diff --git a/dokkatoo-mkdocs/README.md b/dokkatoo-mkdocs/README.md deleted file mode 100644 index 3665108..0000000 --- a/dokkatoo-mkdocs/README.md +++ /dev/null @@ -1,54 +0,0 @@ -# Module Dokkatoo: Material for MkDocs format - -Gradle plugin to configure Dokkatoo with Material for MkDocs. - - - - - -This is a Gradle plugin using [Dokkatoo](https://github.com/adamko-dev/dokkatoo) to extract Kotlin documentation and embed it in a Material for MkDocs site. To learn more about the project, see [the documentation](https://opensavvy.gitlab.io/automation/dokka-material-mkdocs/docs/). - -## Configuration - -Create a `build.gradle.kts` file in the same directory as your `mkdocs.yml` file: -```kotlin -id("dev.opensavvy.dokkatoo-mkdocs") version "VERSION HERE" - -dependencies { - // Embeds the documentation from project :foo-bar - dokkatoo(project("foo-bar")) -} -``` - -Add each project that you want to document in the `dependencies {}` block. Each project mentioned in that way must have the Dokkatoo plugin applied. - -Add the directory in which you created the project in the `settings.gradle.kts` file: -```kotlin -// Everything else… - -include("docs") // or whatever other path you used -``` - -In `mkdocs.yml`, add the marker of where you want the documentation to be generated: -```yaml -# Everything else… - -nav: - - Home: # your existing pages… - - index.md - - setup.md - - - Another: another.md # your existing pages… - -# !!! EMBEDDED DOKKA START, DO NOT COMMIT !!! # -# !!! EMBEDDED DOKKA END, DO NOT COMMIT !!! # - - - Whatever: whatever.md # your existing pages… -``` - -## Running - -Run the following command, replacing `docs` by the project path of where you put your documentation: -```shell -./gradlew docs:embedDokkaIntoMkDocs -``` diff --git a/dokkatoo-mkdocs/build.gradle.kts b/dokkatoo-mkdocs/build.gradle.kts deleted file mode 100644 index 8ec05b4..0000000 --- a/dokkatoo-mkdocs/build.gradle.kts +++ /dev/null @@ -1,64 +0,0 @@ -import org.jetbrains.dokka.gradle.tasks.DokkaGenerateTask - -plugins { - `kotlin-dsl` - alias(opensavvyConventions.plugins.base) - alias(opensavvyConventions.plugins.kotlin.abstractLibrary) - alias(opensavvyConventions.plugins.plugin) -} - -dependencies { - implementation(libs.gradle.dokkatoo) -} - -gradlePlugin { - plugins { - register("dokkatoo-mkdocs") { - id = "dev.opensavvy.dokkatoo-mkdocs" - implementationClass = "opensavvy.dokka.gradle.DokkatooMkDocsPlugin" - } - } -} - -library { - name.set("Dokkatoo: Material for MkDocs format") - description.set("Gradle plugin to add the Material for MkDocs format to Dokkatoo") - homeUrl.set("https://opensavvy.gitlab.io/automation/dokka-material-mkdocs/docs/") - - license.set { - name.set("Apache 2.0") - url.set("https://www.apache.org/licenses/LICENSE-2.0.txt") - } -} - -val embedCurrentVersion by tasks.registering { - description = "Embeds the current version into the source code" - - val version = project.version as String - val file = File(kotlin.sourceSets.main.get().kotlin.srcDirs.first(), "version.kt") - - inputs.property("version", version) - outputs.file(file) - - doLast { - file.writeText( - """ - // Generated file, do not edit - package opensavvy.dokka.gradle - internal const val DokkaMkDocsVersion = "$version" - """.trimIndent() - ) - } -} - -tasks.compileKotlin { - dependsOn(embedCurrentVersion) -} - -tasks.sourcesJar { - dependsOn(embedCurrentVersion) -} - -tasks.withType { - dependsOn(embedCurrentVersion) -} diff --git a/dokkatoo-mkdocs/src/main/kotlin/.gitignore b/dokkatoo-mkdocs/src/main/kotlin/.gitignore deleted file mode 100644 index a59111e..0000000 --- a/dokkatoo-mkdocs/src/main/kotlin/.gitignore +++ /dev/null @@ -1 +0,0 @@ -version.kt diff --git a/dokkatoo-mkdocs/src/main/kotlin/DokkatooMkDocsPlugin.kt b/dokkatoo-mkdocs/src/main/kotlin/DokkatooMkDocsPlugin.kt deleted file mode 100644 index ef87bba..0000000 --- a/dokkatoo-mkdocs/src/main/kotlin/DokkatooMkDocsPlugin.kt +++ /dev/null @@ -1,130 +0,0 @@ -package opensavvy.dokka.gradle - -import dev.adamko.dokkatoo.formats.DokkatooFormatPlugin -import dev.adamko.dokkatoo.internal.DokkatooInternalApi -import org.gradle.api.Project -import org.gradle.api.file.DuplicatesStrategy -import org.gradle.api.tasks.Sync -import org.gradle.kotlin.dsl.* - -@OptIn(DokkatooInternalApi::class) -abstract class DokkatooMkDocsPlugin : DokkatooFormatPlugin(formatName = "mkdocs") { - - override fun apply(target: Project) { - super.apply(target) - - val dokkatooMkdocsModuleOutputDirectoriesResolver by target.configurations.getting - - val siteOutput = target.layout.projectDirectory.dir("docs/api") - val navOutput = target.layout.buildDirectory.file("mkdocs/navigation.yaml") - - val dokkatooCopyIntoMkDocs by target.tasks.registering(Sync::class) { - group = "dokkatoo" - description = "Copies the Dokkatoo pages into the website." - - from(dokkatooMkdocsModuleOutputDirectoriesResolver) - into(siteOutput) - - eachFile { - path = path.removePrefix("module/") - } - - exclude("includes/*") - - includeEmptyDirs = true - duplicatesStrategy = DuplicatesStrategy.WARN // TODO make each module generate files in its own directory, afterwards remove this - } - - val generateMkDocsNavigation by target.tasks.registering { - group = "dokkatoo" - description = "Scans the generated documentation files to generate the MkDocs index" - - inputs.files(dokkatooCopyIntoMkDocs) - outputs.file(navOutput) - - doLast { - val root = siteOutput.asFile - val builder = StringBuilder() - var depth = 1 - - root.walkTopDown() - .onEnter { file -> - // Ignore directories that only contain other directories - file.walkBottomUp().any { it.isFile } - } - .onLeave { - if (it.isDirectory) - depth-- - } - .forEach { file -> - val relative = file.relativeTo(root) - - val indent = " ".repeat(depth) + " " - - when { - file == root -> { - builder.appendLine(" - Reference (experimental):") - } - - file.isDirectory -> { - builder.appendLine("$indent- ${relative.name.decodeAsDokkaUrl()}:") - depth++ - } - - file.isFile && file.name.endsWith(".md") -> { - builder.appendLine("$indent- api/$relative") - } - } - } - - navOutput.get().asFile.writeText(builder.toString()) - } - } - - val mkdocsYaml = target.layout.projectDirectory.file("mkdocs.yml") - val embedMkDocsNavigation by target.tasks.registering { - group = "dokkatoo" - description = "Adds all the generated files to the index of the MkDocs site" - - inputs.files(generateMkDocsNavigation) - inputs.file(mkdocsYaml) - outputs.file(mkdocsYaml) - - doLast { - val startMarker = "# !!! EMBEDDED DOKKA START, DO NOT COMMIT !!! #" - val endMarker = "# !!! EMBEDDED DOKKA END, DO NOT COMMIT !!! #" - - val lines = mkdocsYaml.asFile.readLines() - val start = lines.takeWhile { it != startMarker } - val end = lines.takeLastWhile { it != endMarker } - - val embeds = navOutput.get().asFile.readLines() - - val output = start + startMarker + embeds + endMarker + end - mkdocsYaml.asFile.writeText(output.joinToString(System.lineSeparator()) + System.lineSeparator()) - } - } - - val embedDokkaIntoMkDocs by target.tasks.registering { - group = "dokkatoo" - description = "Lifecycle task to embed configured Dokkatoo modules into a Material for MkDocs website" - - dependsOn(dokkatooCopyIntoMkDocs, embedMkDocsNavigation) - } - } - - override fun DokkatooFormatPluginContext.configure() { - project.dependencies { - dokkaPlugin("dev.opensavvy.dokka.mkdocs:renderer:$DokkaMkDocsVersion") - } - } -} - -fun String.decodeAsDokkaUrl(): String { - var result = this - var index: Int - while (result.indexOf('-').also { index = it } >= 0) { - result = result.substring(0 until index) + result[index + 1].uppercase() + result.substring(index + 2) - } - return result -} diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml index c6ffa85..704b663 100644 --- a/gradle/libs.versions.toml +++ b/gradle/libs.versions.toml @@ -3,7 +3,6 @@ [versions] coroutines = "1.10.1" # https://github.com/Kotlin/kotlinx.coroutines/releases dokka = "2.0.0-Beta" # https://github.com/Kotlin/dokka/releases -dokkatoo = "2.3.1" # https://github.com/adamko-dev/dokkatoo/releases [plugins] @@ -14,6 +13,5 @@ dokka-base = { module = "org.jetbrains.dokka:dokka-base", version.ref = "dokka" dokka-core = { module = "org.jetbrains.dokka:dokka-core", version.ref = "dokka" } gradle-dokka = { module = "org.jetbrains.dokka:dokka-gradle-plugin", version.ref = "dokka" } -gradle-dokkatoo = { module = "dev.adamko.dokkatoo:dokkatoo-plugin", version.ref = "dokkatoo" } [bundles] diff --git a/renderer/README.md b/renderer/README.md index e6ff3e5..eed16f6 100644 --- a/renderer/README.md +++ b/renderer/README.md @@ -6,4 +6,4 @@ Dokka plugin to generate a Material for MkDocs compatible Markdown collection of -This plugin is usually not used directly. Instead, use one of the Gradle plugins to configure Dokka or Dokkatoo. +This plugin is usually not used directly. Instead, use one of the Gradle plugins to configure Dokka. diff --git a/settings.gradle.kts b/settings.gradle.kts index ed7da81..2035852 100644 --- a/settings.gradle.kts +++ b/settings.gradle.kts @@ -54,7 +54,6 @@ plugins { include( "renderer", - "dokkatoo-mkdocs", "dokka-mkdocs", "gradle:templates:template-app",