diff --git a/docs/website/build.gradle.kts b/docs/website/build.gradle.kts new file mode 100644 index 0000000..fba7b67 --- /dev/null +++ b/docs/website/build.gradle.kts @@ -0,0 +1,8 @@ +plugins { + alias(opensavvyConventions.plugins.base) + id("dev.opensavvy.dokkatoo-mkdocs-combine") version "VERSION HERE" +} + +dependencies { + mkdocsWebsite(projects.example.exampleCore) +} diff --git a/docs/website/docs/api/.gitignore b/docs/website/docs/api/.gitignore new file mode 100644 index 0000000..72e8ffc --- /dev/null +++ b/docs/website/docs/api/.gitignore @@ -0,0 +1 @@ +* diff --git a/docs/website/mkdocs.yml b/docs/website/mkdocs.yml index 9ead25d..35a5bf5 100644 --- a/docs/website/mkdocs.yml +++ b/docs/website/mkdocs.yml @@ -93,3 +93,14 @@ nav: - Reference: - reference.md + + # TODO: all of this should be generated by the plugin + - API: + - example-core: + - api/index.md + - opensavvy.dokka.material.mkdocs.example: + - api/example-core/opensavvy.dokka.material.mkdocs.example/index.md + - Example: + - api/example-core/opensavvy.dokka.material.mkdocs.example/-example/index.md + - foo: api/example-core/opensavvy.dokka.material.mkdocs.example/-example/foo.md + - Example: api/example-core/opensavvy.dokka.material.mkdocs.example/-example/-example.md diff --git a/example/example-core/src/commonMain/kotlin/Example.kt b/example/example-core/src/commonMain/kotlin/Example.kt index 787b03a..42e75a8 100644 --- a/example/example-core/src/commonMain/kotlin/Example.kt +++ b/example/example-core/src/commonMain/kotlin/Example.kt @@ -2,12 +2,16 @@ package opensavvy.dokka.material.mkdocs.example /** * This class is an example to see how the documentation website is generated. + * + * @constructor Public constructor for the [Example] class. */ class Example { /** * This is an example function. * + * This is a reference to a parameter: [bar]. + * * @param bar This is a parameter. * @return This is a return type. */ diff --git a/gradle/conventions/dokkatoo-mkdocs-combine/build.gradle.kts b/gradle/conventions/dokkatoo-mkdocs-combine/build.gradle.kts new file mode 100644 index 0000000..189f386 --- /dev/null +++ b/gradle/conventions/dokkatoo-mkdocs-combine/build.gradle.kts @@ -0,0 +1,26 @@ +plugins { + `kotlin-dsl` + alias(opensavvyConventions.plugins.base) + alias(opensavvyConventions.plugins.kotlin.abstractLibrary) + alias(opensavvyConventions.plugins.plugin) +} + +gradlePlugin { + plugins { + register("dokkatoo-mkdocs-combine") { + id = "dev.opensavvy.dokkatoo-mkdocs-combine" + implementationClass = "opensavvy.dokka.gradle.DokkatooMkDocsCombinatorPlugin" + } + } +} + +library { + name.set("Integrates outputs of the Material for MkDocs dokka format into a Material for MkDocs website") + description.set("Gradle plugin to integrate Dokka into a Material for MkDocs website") + homeUrl.set("https://gitlab.com/opensavvy/automation/dokka-material-mkdocs") + + license.set { + name.set("Apache 2.0") + url.set("https://www.apache.org/licenses/LICENSE-2.0.txt") + } +} diff --git a/gradle/conventions/dokkatoo-mkdocs-combine/src/main/kotlin/DokkatooMkDocsCombinatorPlugin.kt b/gradle/conventions/dokkatoo-mkdocs-combine/src/main/kotlin/DokkatooMkDocsCombinatorPlugin.kt new file mode 100644 index 0000000..95c8ae1 --- /dev/null +++ b/gradle/conventions/dokkatoo-mkdocs-combine/src/main/kotlin/DokkatooMkDocsCombinatorPlugin.kt @@ -0,0 +1,30 @@ +package opensavvy.dokka.gradle + +import org.gradle.api.Plugin +import org.gradle.api.Project +import org.gradle.api.attributes.Bundling +import org.gradle.api.attributes.Category +import org.gradle.api.attributes.LibraryElements +import org.gradle.api.tasks.Sync +import org.gradle.kotlin.dsl.* +import java.io.File + +class DokkatooMkDocsCombinatorPlugin : Plugin { + + override fun apply(target: Project) { + val mkdocsWebsite by target.configurations.creating { + isCanBeConsumed = false + + attributes { + attribute(Category.CATEGORY_ATTRIBUTE, target.objects.named(Category.DOCUMENTATION)) + attribute(Bundling.BUNDLING_ATTRIBUTE, target.objects.named(Bundling.EXTERNAL)) + attribute(LibraryElements.LIBRARY_ELEMENTS_ATTRIBUTE, target.objects.named("mkdocs-pages")) + } + } + + val embedDokkaIntoMkDocs by target.tasks.registering(Sync::class) { + from(mkdocsWebsite) + into(target.layout.dir(target.provider { File("docs/api") })) + } + } +} diff --git a/gradle/conventions/dokkatoo-mkdocs/src/main/kotlin/DokkatooMkDocsPlugin.kt b/gradle/conventions/dokkatoo-mkdocs/src/main/kotlin/DokkatooMkDocsPlugin.kt index 92d7fa4..4e7f0cc 100644 --- a/gradle/conventions/dokkatoo-mkdocs/src/main/kotlin/DokkatooMkDocsPlugin.kt +++ b/gradle/conventions/dokkatoo-mkdocs/src/main/kotlin/DokkatooMkDocsPlugin.kt @@ -2,11 +2,35 @@ 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.attributes.Bundling +import org.gradle.api.attributes.Category +import org.gradle.api.attributes.LibraryElements +import org.gradle.kotlin.dsl.creating import org.gradle.kotlin.dsl.dependencies +import org.gradle.kotlin.dsl.getValue +import org.gradle.kotlin.dsl.named @OptIn(DokkatooInternalApi::class) abstract class DokkatooMkDocsPlugin : DokkatooFormatPlugin(formatName = "mkdocs") { + override fun apply(target: Project) { + super.apply(target) + + val materialForMkDocsPages by target.configurations.creating { + isCanBeConsumed = true + isCanBeResolved = true + + attributes { + attribute(Category.CATEGORY_ATTRIBUTE, target.objects.named(Category.DOCUMENTATION)) + attribute(Bundling.BUNDLING_ATTRIBUTE, target.objects.named(Bundling.EXTERNAL)) + attribute(LibraryElements.LIBRARY_ELEMENTS_ATTRIBUTE, target.objects.named("mkdocs-pages")) + } + } + + target.artifacts.add(materialForMkDocsPages.name, target.tasks.named("dokkatooGeneratePublicationMkdocs")) + } + override fun DokkatooFormatPluginContext.configure() { project.dependencies { dokkaPlugin("dev.opensavvy.dokka.mkdocs:renderer:1.0.0") diff --git a/gradle/conventions/settings.gradle.kts b/gradle/conventions/settings.gradle.kts index 8b615de..05ea4b8 100644 --- a/gradle/conventions/settings.gradle.kts +++ b/gradle/conventions/settings.gradle.kts @@ -50,4 +50,5 @@ enableFeaturePreview("TYPESAFE_PROJECT_ACCESSORS") include( "dokkatoo-mkdocs", + "dokkatoo-mkdocs-combine", ) diff --git a/settings.gradle.kts b/settings.gradle.kts index 8fcd133..301e163 100644 --- a/settings.gradle.kts +++ b/settings.gradle.kts @@ -57,4 +57,5 @@ include( "gradle:templates:template-app", "gradle:templates:template-lib", + "docs:website", ) -- 2.51.2 From 3e1721c13859f6be8e446054b4b85bf192c284dc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= Date: Thu, 8 Aug 2024 22:47:31 +0200 Subject: [PATCH 2/2] feat(dokkatoo-mkdocs): Merge the combinator plugin into the regular plugin This is better because Dokkatoo handles everything for us: https://github.com/adamko-dev/dokkatoo/discussions/262#discussioncomment-10257877 --- docs/website/build.gradle.kts | 4 +-- .../dokkatoo-mkdocs-combine/build.gradle.kts | 26 ---------------- .../kotlin/DokkatooMkDocsCombinatorPlugin.kt | 30 ------------------- .../src/main/kotlin/DokkatooMkDocsPlugin.kt | 24 +++++---------- gradle/conventions/settings.gradle.kts | 1 - 5 files changed, 9 insertions(+), 76 deletions(-) delete mode 100644 gradle/conventions/dokkatoo-mkdocs-combine/build.gradle.kts delete mode 100644 gradle/conventions/dokkatoo-mkdocs-combine/src/main/kotlin/DokkatooMkDocsCombinatorPlugin.kt diff --git a/docs/website/build.gradle.kts b/docs/website/build.gradle.kts index fba7b67..3c23549 100644 --- a/docs/website/build.gradle.kts +++ b/docs/website/build.gradle.kts @@ -1,8 +1,8 @@ plugins { alias(opensavvyConventions.plugins.base) - id("dev.opensavvy.dokkatoo-mkdocs-combine") version "VERSION HERE" + id("dev.opensavvy.dokkatoo-mkdocs") version "VERSION HERE" } dependencies { - mkdocsWebsite(projects.example.exampleCore) + dokkatoo(projects.example.exampleCore) } diff --git a/gradle/conventions/dokkatoo-mkdocs-combine/build.gradle.kts b/gradle/conventions/dokkatoo-mkdocs-combine/build.gradle.kts deleted file mode 100644 index 189f386..0000000 --- a/gradle/conventions/dokkatoo-mkdocs-combine/build.gradle.kts +++ /dev/null @@ -1,26 +0,0 @@ -plugins { - `kotlin-dsl` - alias(opensavvyConventions.plugins.base) - alias(opensavvyConventions.plugins.kotlin.abstractLibrary) - alias(opensavvyConventions.plugins.plugin) -} - -gradlePlugin { - plugins { - register("dokkatoo-mkdocs-combine") { - id = "dev.opensavvy.dokkatoo-mkdocs-combine" - implementationClass = "opensavvy.dokka.gradle.DokkatooMkDocsCombinatorPlugin" - } - } -} - -library { - name.set("Integrates outputs of the Material for MkDocs dokka format into a Material for MkDocs website") - description.set("Gradle plugin to integrate Dokka into a Material for MkDocs website") - homeUrl.set("https://gitlab.com/opensavvy/automation/dokka-material-mkdocs") - - license.set { - name.set("Apache 2.0") - url.set("https://www.apache.org/licenses/LICENSE-2.0.txt") - } -} diff --git a/gradle/conventions/dokkatoo-mkdocs-combine/src/main/kotlin/DokkatooMkDocsCombinatorPlugin.kt b/gradle/conventions/dokkatoo-mkdocs-combine/src/main/kotlin/DokkatooMkDocsCombinatorPlugin.kt deleted file mode 100644 index 95c8ae1..0000000 --- a/gradle/conventions/dokkatoo-mkdocs-combine/src/main/kotlin/DokkatooMkDocsCombinatorPlugin.kt +++ /dev/null @@ -1,30 +0,0 @@ -package opensavvy.dokka.gradle - -import org.gradle.api.Plugin -import org.gradle.api.Project -import org.gradle.api.attributes.Bundling -import org.gradle.api.attributes.Category -import org.gradle.api.attributes.LibraryElements -import org.gradle.api.tasks.Sync -import org.gradle.kotlin.dsl.* -import java.io.File - -class DokkatooMkDocsCombinatorPlugin : Plugin { - - override fun apply(target: Project) { - val mkdocsWebsite by target.configurations.creating { - isCanBeConsumed = false - - attributes { - attribute(Category.CATEGORY_ATTRIBUTE, target.objects.named(Category.DOCUMENTATION)) - attribute(Bundling.BUNDLING_ATTRIBUTE, target.objects.named(Bundling.EXTERNAL)) - attribute(LibraryElements.LIBRARY_ELEMENTS_ATTRIBUTE, target.objects.named("mkdocs-pages")) - } - } - - val embedDokkaIntoMkDocs by target.tasks.registering(Sync::class) { - from(mkdocsWebsite) - into(target.layout.dir(target.provider { File("docs/api") })) - } - } -} diff --git a/gradle/conventions/dokkatoo-mkdocs/src/main/kotlin/DokkatooMkDocsPlugin.kt b/gradle/conventions/dokkatoo-mkdocs/src/main/kotlin/DokkatooMkDocsPlugin.kt index 4e7f0cc..2c899d8 100644 --- a/gradle/conventions/dokkatoo-mkdocs/src/main/kotlin/DokkatooMkDocsPlugin.kt +++ b/gradle/conventions/dokkatoo-mkdocs/src/main/kotlin/DokkatooMkDocsPlugin.kt @@ -3,13 +3,9 @@ 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.attributes.Bundling -import org.gradle.api.attributes.Category -import org.gradle.api.attributes.LibraryElements -import org.gradle.kotlin.dsl.creating -import org.gradle.kotlin.dsl.dependencies -import org.gradle.kotlin.dsl.getValue -import org.gradle.kotlin.dsl.named +import org.gradle.api.tasks.Sync +import org.gradle.kotlin.dsl.* +import java.io.File @OptIn(DokkatooInternalApi::class) abstract class DokkatooMkDocsPlugin : DokkatooFormatPlugin(formatName = "mkdocs") { @@ -17,18 +13,12 @@ abstract class DokkatooMkDocsPlugin : DokkatooFormatPlugin(formatName = "mkdocs" override fun apply(target: Project) { super.apply(target) - val materialForMkDocsPages by target.configurations.creating { - isCanBeConsumed = true - isCanBeResolved = true + val dokkatooMkdocsModuleOutputDirectoriesResolver by target.configurations.getting - attributes { - attribute(Category.CATEGORY_ATTRIBUTE, target.objects.named(Category.DOCUMENTATION)) - attribute(Bundling.BUNDLING_ATTRIBUTE, target.objects.named(Bundling.EXTERNAL)) - attribute(LibraryElements.LIBRARY_ELEMENTS_ATTRIBUTE, target.objects.named("mkdocs-pages")) - } + val embedDokkaIntoMkDocs by target.tasks.registering(Sync::class) { + from(dokkatooMkdocsModuleOutputDirectoriesResolver) + into(target.layout.dir(target.provider { File("docs/api") })) } - - target.artifacts.add(materialForMkDocsPages.name, target.tasks.named("dokkatooGeneratePublicationMkdocs")) } override fun DokkatooFormatPluginContext.configure() { diff --git a/gradle/conventions/settings.gradle.kts b/gradle/conventions/settings.gradle.kts index 05ea4b8..8b615de 100644 --- a/gradle/conventions/settings.gradle.kts +++ b/gradle/conventions/settings.gradle.kts @@ -50,5 +50,4 @@ enableFeaturePreview("TYPESAFE_PROJECT_ACCESSORS") include( "dokkatoo-mkdocs", - "dokkatoo-mkdocs-combine", )