Merge pull request #81 from modelix/feat/dokka-setup

MODELIX-429: Automatic API reference generation

Author: mhuster23

.github/workflows/docs.yaml

@@ -0,0 +1,27 @@
+name: Build and Publish Docs
+
+on:
+  push:
+    tags:
+      - '[0-9]+.[0-9]+.0'  # New Major or Minor Releases
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Project
+        uses: actions/checkout@v3
+      - name: Set up JDK 11
+        uses: actions/setup-java@v3
+        with:
+          distribution: 'temurin'
+          java-version: '11'
+      - name: Use tag as version
+        run: echo "${GITHUB_REF#refs/*/}" > version.txt
+      - name: Generate Docs with Dokka
+        run: ./gradlew dokkaHtmlMultiModule
+      - name: Publish to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: build/dokka
+          keep_files: true

build.gradle.kts

@@ -1,3 +1,14 @@
+import kotlinx.html.*
+import kotlinx.html.stream.createHTML
+import org.jetbrains.dokka.base.DokkaBase
+import org.jetbrains.dokka.base.DokkaBaseConfiguration
+
+buildscript {
+    dependencies {
+        classpath("org.jetbrains.dokka:versioning-plugin:1.8.10")
+    }
+}
+
 plugins {
     kotlin("multiplatform") apply false
     kotlin("plugin.serialization") apply false
@@ -6,6 +17,13 @@ plugins {
     id("org.jlleitschuh.gradle.ktlint") version "10.3.0" apply false
     id("com.diffplug.spotless") version "5.0.0" apply false
     id("com.dorongold.task-tree") version "2.1.0"
+    id("org.jetbrains.dokka") version "1.8.10"
+}
+
+repositories {
+    mavenLocal()
+    maven { url = uri("https://artifacts.itemis.cloud/repository/maven-mps/") }
+    mavenCentral()
 }
 
 group = "org.modelix"
@@ -23,8 +41,13 @@ fun computeVersion(): Any {
     }
 }
 
+dependencies {
+    dokkaPlugin("org.jetbrains.dokka:versioning-plugin:1.8.10")
+}
+
 subprojects {
     apply(plugin = "maven-publish")
+    apply(plugin = "org.jetbrains.dokka")
     version = rootProject.version
     group = rootProject.group
 
@@ -88,3 +111,122 @@ subprojects {
 tasks.withType<org.jetbrains.kotlin.gradle.targets.js.npm.tasks.KotlinNpmInstallTask> {
     dependsOn(":ts-model-api:npm_run_build")
 }
+val docsDir = buildDir.resolve("dokka")
+
+tasks.dokkaHtmlMultiModule {
+    outputDirectory.set(docsDir.resolve("$version"))
+    pluginConfiguration<DokkaBase, DokkaBaseConfiguration> {
+        customAssets += file(projectDir.resolve("dokka/logo-dark.svg"))
+        customStyleSheets += file(projectDir.resolve("dokka/logo-styles.css"))
+        footerMessage = createFooterMessage()
+    }
+    doLast {
+        val index = file(docsDir.resolve("index.html"))
+        index.writeText(createDocsIndexPage(), Charsets.ISO_8859_1)
+    }
+}
+
+fun createFooterMessage(): String {
+    return createHTML().span {
+        createFooter()
+    }
+}
+
+fun FlowContent.createFooter() {
+    p {
+        +"For more information visit "
+        a("https://modelix.org") { +"modelix.org" }
+        +", for further documentation visit "
+        a("https://docs.modelix.org") { +"docs.modelix.org" }
+        +"."
+    }
+    p {
+        +"Copyright \u00A9 2021-present by the "
+        a("https://modelix.org") { +"modelix open source project" }
+        +" and the individual contributors. All Rights reserved."
+    }
+    p {
+        +"Except where otherwise noted, "
+        a("https://api.modelix.org")  {+"api.modelix.org"}
+        +", modelix, and the modelix framework, are licensed under the "
+        a("https://www.apache.org/licenses/LICENSE-2.0.html") { +"Apache-2.0 license"}
+        +"."
+    }
+}
+
+fun createDocsIndexPage(): String {
+    return createHTML().html {
+        head {
+            link(href = "./$version/styles/style.css", rel = "Stylesheet")
+            link(href = "./$version/styles/logo-styles.css", rel = "Stylesheet")
+            title("modelix.core API Reference")
+            style {
+                unsafe {
+                    +"""
+                    .library-name {
+                        padding-top: 6px;
+                        padding-bottom: 6px;
+                    }
+                """.trimIndent()
+                }
+            }
+        }
+        body {
+            div("navigation-wrapper") {
+                id = "navigation-wrapper"
+                div("library-name") {
+                    a { +"modelix.core API Reference" }
+                }
+            }
+            div("wrapper") {
+                id = "container"
+                div {
+                    id ="leftColumn"
+                }
+                div {
+                    id = "main"
+                    div("main-content") {
+                        id ="content"
+                        div("breadcrumbs")
+                        div("cover") {
+                            h2 { +"Available versions:" }
+                            div("table") {
+                                val versionDirs = docsDir.listFiles()
+                                    ?.filter { it.isDirectory }
+                                    ?.sortedByDescending { it.name }
+                                if (versionDirs != null) {
+                                    for (versionDir in versionDirs) {
+                                        val versionIndex = versionDir.resolve("index.html")
+                                        if (versionIndex.exists()) {
+                                            div("table-row") {
+                                                div("main-subrow") {
+                                                    div("w-100") {
+                                                        span("inline-flex") {
+                                                            a( href = versionIndex.relativeTo(docsDir).path) {
+                                                                +"modelix.core ${versionDir.name}"
+                                                            }
+                                                        }
+                                                    }
+                                                }
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    }
+                    div("footer") {
+                        span("go-to-top-icon") {
+                            a("#content") {
+                                id = "go-to-top-link"
+                            }
+                        }
+                        span {
+                            createFooter()
+                        }
+                    }
+                }
+            }
+        }
+    }
+}

dokka/logo-dark.svg

@@ -0,0 +1,15 @@
+.library-name a {
+    position: relative;
+    margin-left: 55px;
+}
+
+.library-name a::before {
+    content: '';
+    background: url('../images/logo-dark.svg') center no-repeat;
+    background-size: contain;
+    position: absolute;
+    width: 50px;
+    height: 50px;
+    top: -18px;
+    left: -55px;
+}

dokka/logo-styles.css

@@ -1,3 +1,4 @@
+org.gradle.jvmargs=-Xmx512m "-XX:MaxMetaspaceSize=2g"
 systemProp.org.gradle.internal.http.socketTimeout=120000
 kotlin.daemon.jvmargs=-Xmx2G