docs: rework dokka generation (#104)

utybo · Oct 31, 2024 · 1307dac · 1307dac
1 parent fbb6f48
commit 1307dac
Show file tree

Hide file tree

Showing 16 changed files with 185 additions and 132 deletions.
diff --git a/build.gradle b/build.gradle
@@ -1,10 +1,2 @@
-plugins {
-    id 'org.jetbrains.dokka'
-}
-
-repositories {
-    mavenCentral()
-}
-
 group = "guru.zoroark.tegral"
 version = rootProject.file('version.txt').text.trim()
diff --git a/buildSrc/build.gradle b/buildSrc/build.gradle
@@ -10,7 +10,7 @@ dependencies {
     def pluginsDef = [
         libs.plugins.kotlin,
         libs.plugins.kotlinSerialization,
-        libs.plugins.dokka,
+        libs.plugins.dokkatoo,
         libs.plugins.detekt,
         libs.plugins.versions,
         libs.plugins.gradleTestLogger,

diff --git a/buildSrc/src/main/groovy/guru.zoroark.tegral.kotlin-published-library-conventions.gradle b/buildSrc/src/main/groovy/guru.zoroark.tegral.kotlin-published-library-conventions.gradle
@@ -1,7 +1,7 @@
 plugins {
     id 'guru.zoroark.tegral.kotlin-common-conventions'
     id 'guru.zoroark.tegral.publish-conventions'
-    id 'org.jetbrains.dokka'
+    id 'dev.adamko.dokkatoo'
     id 'org.jetbrains.kotlinx.binary-compatibility-validator'
     id 'maven-publish'
     id 'signing'
@@ -14,9 +14,9 @@ detekt {
     buildUponDefaultConfig = true
 }
 
-tasks.dokkaHtmlPartial {
-    dokkaSourceSets {
-        configureEach {
+afterEvaluate {
+    dokkatoo {
+        dokkatooSourceSets.configureEach {
             includes.from("MODULE.md")
         }
     }

diff --git a/code-coverage/build.gradle b/code-coverage/build.gradle
@@ -7,49 +7,10 @@ repositories {
     mavenCentral()
 }
 
-def projects = [
-    ':tegral-config:tegral-config-core',
-    ':tegral-core',
-    ':tegral-di:tegral-di-core',
-    ':tegral-di:tegral-di-services',
-    ':tegral-di:tegral-di-test',
-    ':tegral-di:tegral-di-test-mockk',
-    ':tegral-featureful',
-    ':tegral-logging',
-    ':tegral-niwen:tegral-niwen-lexer',
-    ':tegral-niwen:tegral-niwen-parser',
-    ':tegral-openapi:tegral-openapi-cli',
-    ':tegral-openapi:tegral-openapi-dsl',
-    ':tegral-openapi:tegral-openapi-feature',
-    ':tegral-openapi:tegral-openapi-ktor',
-    ':tegral-openapi:tegral-openapi-ktor-resources',
-    ':tegral-openapi:tegral-openapi-ktorui',
-    ':tegral-openapi:tegral-openapi-scriptdef',
-    ':tegral-openapi:tegral-openapi-scripthost',
-    ':tegral-prismakt:tegral-prismakt-generator',
-    ':tegral-services:tegral-services-api',
-    ':tegral-services:tegral-services-feature',
-    ':tegral-utils:tegral-utils-logtools',
-    ':tegral-web:tegral-web-appdefaults',
-    ':tegral-web:tegral-web-appdsl',
-    ':tegral-web:tegral-web-apptest',
-    ':tegral-web:tegral-web-config',
-    ':tegral-web:tegral-web-controllers',
-    ':tegral-web:tegral-web-controllers-test',
-    ':tegral-web:tegral-web-greeter',
-    ':e2e-tests:run-with-java-11',
-    ':e2e-tests:run-with-java-17',
-    ':e2e-tests:run-without-config'
-]
-
 dependencies {
-    for (projectPath in projects) {
+    for (projectPath in gradle.ext.testProjects) {
         aggregatedProjects project(projectPath)
     }
-
-    for (prismaktTestProject in project(':tegral-prismakt:tegral-prismakt-generator-tests').subprojects) {
-        aggregatedProjects prismaktTestProject
-    }
 }
 
 tasks.named('check') {

diff --git a/docs/blog/2022-06-02-tegral-001/index.md b/docs/blog/2022-06-02-tegral-001/index.md
@@ -50,7 +50,7 @@ Currently, Tegral has quite a few elements:
 
 - Documentation!
   - This very website
-  - The [API](pathname:///dokka) documentation, made available using Dokka.
+  - The [API](pathname:///dokka/index.html) documentation, made available using Dokka.
 - Libraries!
   - And quite a lot of them! Just dig into the documentation to find out what the different components can all do for you.
   - Most notably, Tegral includes a [powerful DI framework called Tegral DI](pathname:///docs/modules/core/di) that is the successor to [Shedinja](https://shedinja.zoroark.guru).

diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts
@@ -85,7 +85,7 @@ export default {
             label: "About",
           },
           {
-            href: "pathname:///dokka",
+            href: "pathname:///dokka/index.html",
             label: "API",
             position: "right",
           },
@@ -118,7 +118,7 @@ export default {
               },
               {
                 label: "API documentation (Dokka)",
-                to: "pathname:///dokka",
+                to: "pathname:///dokka/index.html",
               },
             ],
           },

diff --git a/dokka/build.gradle b/dokka/build.gradle
@@ -0,0 +1,32 @@
+plugins {
+    id "dev.adamko.dokkatoo"
+}
+
+repositories {
+    mavenCentral()
+}
+
+configurations {
+    dokkaHtml {
+        canBeConsumed = true
+        canBeResolved = false
+    }
+}
+
+dokkatoo { 
+    moduleName = "Tegral API reference"
+}
+
+version = rootProject.version
+
+dependencies {
+    for (projectPath in gradle.ext.publicProjects) {
+        dokkatoo project(projectPath)
+    }
+}
+
+artifacts {
+    dokkaHtml(tasks.dokkatooGeneratePublicationHtml.outputDirectory) {
+        builtBy(tasks.dokkatooGeneratePublicationHtml)
+    }
+}
diff --git a/.../fundef-modules/src/main/kotlin/guru/zoroark/tegral/e2e/fundefmodules/FundefModulesApp.kt b/.../fundef-modules/src/main/kotlin/guru/zoroark/tegral/e2e/fundefmodules/FundefModulesApp.kt
@@ -126,6 +126,7 @@ fun Application.openApi() {
     }
 }
 
+@OptIn(ExperimentalFundef::class)
 fun app() = tegral {
     install(WebControllersFeature) {
         enableFundefs = true

diff --git a/...ndef-modules/src/test/kotlin/guru/zoroark/tegral/e2e/fundefmodulesm/FundefModulesTests.kt b/...ndef-modules/src/test/kotlin/guru/zoroark/tegral/e2e/fundefmodulesm/FundefModulesTests.kt
@@ -14,11 +14,20 @@
 
 package guru.zoroark.tegral.e2e.fundefmodulesm
 
+import com.fasterxml.jackson.module.kotlin.jacksonObjectMapper
+import com.fasterxml.jackson.module.kotlin.readValue
+import guru.zoroark.tegral.di.environment.get
 import guru.zoroark.tegral.di.test.TegralSubjectTest
 import guru.zoroark.tegral.di.test.mockk.putMock
 import guru.zoroark.tegral.e2e.fundefmodules.Repository
 import guru.zoroark.tegral.e2e.fundefmodules.Service
+import guru.zoroark.tegral.e2e.fundefmodules.app
 import guru.zoroark.tegral.e2e.fundefmodules.controller
+import guru.zoroark.tegral.e2e.fundefmodules.openApi
+import guru.zoroark.tegral.openapi.dsl.openApi
+import guru.zoroark.tegral.openapi.dsl.toJson
+import guru.zoroark.tegral.openapi.ktor.openApi
+import guru.zoroark.tegral.web.appdefaults.DefaultKtorApplication
 import guru.zoroark.tegral.web.controllers.test.TegralControllerTest
 import io.ktor.client.request.delete
 import io.ktor.client.request.get
@@ -31,6 +40,7 @@ import io.mockk.every
 import io.mockk.just
 import io.mockk.runs
 import io.mockk.verifyAll
+import kotlinx.coroutines.runBlocking
 import kotlin.test.Test
 import kotlin.test.assertEquals
 import kotlin.test.assertFails
@@ -171,3 +181,58 @@ class FundefControllerTest : TegralControllerTest<Any>(Routing::controller) {
         verifyAll { service.resetString() }
     }
 }
+
+class FundefOpenapiTest {
+    @Test
+    fun `OpenAPI document`(): Unit = runBlocking {
+        val tegralApp = app()
+        try {
+            val openApiDocument =
+                tegralApp.environment.get<DefaultKtorApplication>().application.openApi.buildOpenApiDocument()
+            val result = jacksonObjectMapper().readValue<Map<*, *>>(openApiDocument.toJson())
+            val expected = jacksonObjectMapper().readValue<Map<*, *>>(
+                """
+                {
+                  "openapi": "3.0.1",
+                  "info": {
+                    "title": "Fundef example",
+                    "description": "An example of a Tegral application that uses fundefs to define modules, etc.",
+                    "version": "0.0.0"
+                  },
+                  "paths": {
+                    "/string": {
+                      "get": {
+                        "summary": "Get the current string value",
+                        "responses": {
+                          "200": {
+                            "description": "Success",
+                            "content": { "text/plain": { "schema": { "type": "string" } } }
+                          },
+                          "404": { "description": "No value currently available" }
+                        }
+                      },
+                      "put": {
+                        "summary": "Set the string value",
+                        "requestBody": {
+                          "content": { "text/plain": { "schema": { "type": "string" } } }
+                        },
+                        "responses": {
+                          "200": { "description": "Set successfully" },
+                          "400": { "description": "Invalid value" }
+                        }
+                      },
+                      "delete": {
+                        "summary": "Reset the string value",
+                        "responses": { "200": { "description": "Reset successfully" } }
+                      }
+                    }
+                  }
+                }
+                """.trimIndent()
+            )
+            assertEquals(expected, result)
+        } finally {
+            tegralApp.stop()
+        }
+    }
+}
diff --git a/e2e-tests/fundef-modules/src/test/resources/tegral.toml b/e2e-tests/fundef-modules/src/test/resources/tegral.toml
@@ -0,0 +1,2 @@
+[tegral.web]
+port = 8991
diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml
@@ -1,7 +1,7 @@
 [versions]
 coroutines = "1.9.0"
-detekt = "1.23.6"  # waiting for a release with a fix for https://github.com/detekt/detekt/issues/7634
-dokka = "1.9.20"
+detekt = "1.23.6"          # waiting for a release with a fix for https://github.com/detekt/detekt/issues/7634
+dokkatoo = "2.3.1"
 gradleTestLogger = "4.0.0"
 hoplite = "2.8.2"
 jackson = "2.18.0"
@@ -41,7 +41,6 @@ kotlin-scripting-jvmHost = { module = "org.jetbrains.kotlin:kotlin-scripting-jvm
 ktor-server-core = { module = "io.ktor:ktor-server-core", version.ref = "ktor" }
 ktor-server-host = { module = "io.ktor:ktor-server-host-common", version.ref = "ktor" }
 ktor-server-netty = { module = "io.ktor:ktor-server-netty", version.ref = "ktor" }
-ktor-server-locations = { module = "io.ktor:ktor-server-locations", version.ref = "ktor" }
 ktor-server-contentNegotiation = { module = "io.ktor:ktor-server-content-negotiation", version.ref = "ktor" }
 ktor-server-test = { module = "io.ktor:ktor-server-test-host", version.ref = "ktor" }
 ktor-server-resources = { module = "io.ktor:ktor-server-resources", version.ref = "ktor" }
@@ -106,7 +105,7 @@ commons-lang3 = { module = "org.apache.commons:commons-lang3", version.ref = "la
 
 kotlin = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin" }
 kotlinSerialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }
-dokka = { id = "org.jetbrains.dokka", version.ref = "dokka" }
+dokkatoo = { id = "dev.adamko.dokkatoo", version.ref = "dokkatoo" }
 detekt = { id = "io.gitlab.arturbosch.detekt", version.ref = "detekt" }
 versions = { id = "com.github.ben-manes.versions", version.ref = "versions" }
 gradleTestLogger = { id = "com.adarshr.test-logger", version.ref = "gradleTestLogger" }

diff --git a/settings.gradle b/settings.gradle
@@ -2,51 +2,67 @@ plugins {
     id "com.gradle.enterprise" version "3.12.2"
 }
 
-// NOTE: When adding projects here, do not forget to also add them as dependencies in the 'code-coverage' project!
-include 'tegral-catalog',
-        'tegral-config:tegral-config-core',
-        'tegral-core',
-        'tegral-di:tegral-di-core',
-        'tegral-di:tegral-di-services',
-        'tegral-di:tegral-di-test',
-        'tegral-di:tegral-di-test-mockk',
-        'tegral-featureful',
-        'tegral-logging',
-        'tegral-niwen:tegral-niwen-lexer',
-        'tegral-niwen:tegral-niwen-parser',
-        'tegral-openapi:tegral-openapi-cli',
-        'tegral-openapi:tegral-openapi-dsl',
-        'tegral-openapi:tegral-openapi-feature',
-        'tegral-openapi:tegral-openapi-ktor',
-        'tegral-openapi:tegral-openapi-ktor-resources',
-        'tegral-openapi:tegral-openapi-ktorui',
-        'tegral-openapi:tegral-openapi-scriptdef',
-        'tegral-openapi:tegral-openapi-scripthost',
-        'tegral-prismakt:tegral-prismakt-generator',
-        'tegral-prismakt:tegral-prismakt-generator-tests:mysql-types',
-        'tegral-prismakt:tegral-prismakt-generator-tests:pgsql-types',
-        'tegral-prismakt:tegral-prismakt-generator-tests:simple-dao',
-        'tegral-prismakt:tegral-prismakt-generator-tests:simple-sql',
-        'tegral-prismakt:tegral-prismakt-generator-tests-support',
-        'tegral-services:tegral-services-api',
-        'tegral-services:tegral-services-feature',
-        'tegral-utils:tegral-utils-logtools',
-        'tegral-web:tegral-web-appdefaults',
-        'tegral-web:tegral-web-appdsl',
-        'tegral-web:tegral-web-apptest',
-        'tegral-web:tegral-web-config',
-        'tegral-web:tegral-web-controllers',
-        'tegral-web:tegral-web-controllers-test',
-        'tegral-web:tegral-web-greeter',
-        'e2e-tests:fundef-modules',
-        'e2e-tests:run-with-java-11',
-        'e2e-tests:run-with-java-17',
-        'e2e-tests:run-without-config'
+def publicProjects = [
+        ':tegral-catalog',
+        ':tegral-config:tegral-config-core',
+        ':tegral-core',
+        ':tegral-di:tegral-di-core',
+        ':tegral-di:tegral-di-services',
+        ':tegral-di:tegral-di-test',
+        ':tegral-di:tegral-di-test-mockk',
+        ':tegral-featureful',
+        ':tegral-logging',
+        ':tegral-niwen:tegral-niwen-lexer',
+        ':tegral-niwen:tegral-niwen-parser',
+        ':tegral-openapi:tegral-openapi-cli',
+        ':tegral-openapi:tegral-openapi-dsl',
+        ':tegral-openapi:tegral-openapi-feature',
+        ':tegral-openapi:tegral-openapi-ktor',
+        ':tegral-openapi:tegral-openapi-ktor-resources',
+        ':tegral-openapi:tegral-openapi-ktorui',
+        ':tegral-openapi:tegral-openapi-scriptdef',
+        ':tegral-openapi:tegral-openapi-scripthost',
+        ':tegral-prismakt:tegral-prismakt-generator',
+        ':tegral-services:tegral-services-api',
+        ':tegral-services:tegral-services-feature',
+        ':tegral-utils:tegral-utils-logtools',
+        ':tegral-web:tegral-web-appdefaults',
+        ':tegral-web:tegral-web-appdsl',
+        ':tegral-web:tegral-web-apptest',
+        ':tegral-web:tegral-web-config',
+        ':tegral-web:tegral-web-controllers',
+        ':tegral-web:tegral-web-controllers-test',
+        ':tegral-web:tegral-web-greeter',
+]
+
+def testProjects = publicProjects - ":tegral-catalog" + [
+        ':tegral-prismakt:tegral-prismakt-generator-tests:mysql-types',
+        ':tegral-prismakt:tegral-prismakt-generator-tests:pgsql-types',
+        ':tegral-prismakt:tegral-prismakt-generator-tests:simple-dao',
+        ':tegral-prismakt:tegral-prismakt-generator-tests:simple-sql',
+        ':tegral-prismakt:tegral-prismakt-generator-tests-support',
+        ':e2e-tests:fundef-modules',
+        ':e2e-tests:run-with-java-11',
+        ':e2e-tests:run-with-java-17',
+        ':e2e-tests:run-without-config'
+]
+
+gradle.ext.publicProjects = publicProjects
+gradle.ext.testProjects = testProjects
+
+for (project in publicProjects) {
+    include project
+}
+for (project in testProjects) {
+    include project
+}
+
 
 include 'examples:simple-json-api'
 
 include 'code-coverage'
 include 'docs'
+include 'dokka'
 include 'website'
 
 gradleEnterprise {

diff --git a/tegral-core/build.gradle b/tegral-core/build.gradle
@@ -20,5 +20,5 @@ sourceSets {
 
 compileKotlin.dependsOn generateKotlin
 checkLicenseMain.dependsOn generateKotlin
-dokkaHtmlPartial.dependsOn generateKotlin
+dokkatooGenerateModuleHtml.dependsOn generateKotlin
 sourcesJar.dependsOn generateKotlin