Arrow: Upgrade to Dokka 1.4-x

[rachelcarmena]

This issue includes the necessary changes to upgrade to Dokka 1.4-x.

Necessary changes

• arrow/gradle.properties: update the version
• Replace dokka by dokkaJekyll in:
  
  
  
  • arrow/scripts/project-run-dokka.sh
  
  
  • arrow/scripts/project-build-doc.sh
  
  
• arrow/doc-conf.gradle

dependencies {
    dokkaHtmlPlugin("org.jetbrains.dokka:jekyll-plugin:$DOKKA_VERSION")
}

dokkaJekyll {
    outputDirectory = "${rootDir}/arrow-docs/docs/apidocs"
    dokkaSourceSets {
        configureEach {
            includes = ['README.md']
            reportUndocumented = false
            classpath = [file("${rootDir}/${project.name}/build/classes/kotlin/main/")]
            samples = ['samples']
            sourceLink {
            ...
        }
    }
}

Changes when using a DEV or EAP version

• Add DEV or EAP repository in arrow/generic-conf.gradle

@@ -19,6 +19,7 @@ allprojects {
         jcenter()
         maven { url 'https://kotlin.bintray.com/kotlinx' }
         maven { url "https://oss.jfrog.org/artifactory/oss-snapshot-local/" }
+        maven { url 'https://dl.bintray.com/kotlin/kotlin-dev' }
     }
 }

• Main build.gradle for arrow library:

@@ -5,8 +5,12 @@ buildscript {
         maven {
             url "https://plugins.gradle.org/m2/"
         }
+        maven {
+          url "https://dl.bintray.com/kotlin/kotlin-dev"
+        }
     }
     dependencies {
+        classpath "org.jetbrains.dokka:dokka-gradle-plugin:$DOKKA_VERSION"
         classpath "org.jetbrains.kotlinx:atomicfu-gradle-plugin:$ATOMICFU_VERSION"
     }
 }
@@ -16,7 +20,7 @@ plugins {
     id "base"
     id "org.jetbrains.kotlin.jvm" version "$KOTLIN_VERSION"
     id "org.jetbrains.kotlin.kapt" version "$KOTLIN_VERSION"
-    id "org.jetbrains.dokka" version "$DOKKA_VERSION" apply false
+    // id "org.jetbrains.dokka" version "$DOKKA_VERSION" apply false
     id "org.jlleitschuh.gradle.ktlint" version "$KTLINT_GRADLE_VERSION"
     id "ru.vyarus.animalsniffer" version "$ANIMALS_SNIFFER_VERSION"
 }

• build.gradle for the modules (except arrow-docs):

@@ -3,11 +3,12 @@ plugins {
     id "base"
     id "org.jetbrains.kotlin.jvm"
     id "org.jetbrains.kotlin.kapt"
-    id "org.jetbrains.dokka"
+    // id "org.jetbrains.dokka"
     id "org.jlleitschuh.gradle.ktlint"
     id "ru.vyarus.animalsniffer"
 }

+apply plugin: "org.jetbrains.dokka"
 apply from: "$SUBPROJECT_CONF"
 apply from: "$DOC_CONF"
 apply from: "$PUBLISH_CONF"

cc: @raulraja @nomisRev

[nomisRev]

cc\ @rachelcarmena https://github.com/Kotlin/dokka/pull/1194

[nomisRev]

Hey @rachelcarmena,

Thanks for trying this out! There is currently a PR open to simplify the Gradle plugin that will break the dokka.
This should stablise their new Gradle API, and their Dokka output seems to also be stable.

[rachelcarmena]

Awesome @nomisRev , thanks for the info!! :raised_hands: I see a small change here (paths are replaced by files): https://github.com/Kotlin/dokka/pull/1194/files#diff-a892d209f9bf6eee5ce6b459af5333d1

[rachelcarmena]

@nomisRev , 1.4.0-rc is available for Dokka now, however https://github.com/Kotlin/dokka/pull/1194 continues being a draft so it seems the proposed changes here are still valid :raised_hands:

[rachelcarmena]

@nomisRev , I tried the latest DEV version and there are some fixes from Dokka 1.4.0-rc :tada:

The new configuration to use the Jekyll Plugin of Dokka 1.4.0-dev-35 version:

dependencies {
    dokkaJekyllPlugin("org.jetbrains.dokka:jekyll-plugin:$DOKKA_VERSION")
}

dokkaJekyll {
    outputDirectory.set(file("${rootDir}/arrow-docs/docs/apidocs"))
    dokkaSourceSets {
        configureEach {
            includes.from('README.md')
            reportUndocumented.set(false)
            classpath.from(file("${rootDir}/${project.name}/build/classes/kotlin/main/"))
            samples.from('samples')
            sourceLink {
                localDirectory.set(file("src/main/kotlin"))
                remoteUrl.set(new java.net.URL("https://github.com/arrow-kt/arrow/blob/master/${relativeProjectPath('src/main/kotlin')}"))
                remoteLineSuffix.set("#L")
            }
        }
    }
}

I also tried Dokka base plugin with dokkaHtml.

Maybe it's necessary additional configuration. Here my feedback:

Both plugins (Base and Jekyll)

Search bar

It's just available for the Dokka base plugin.

Runnable code snippets

It seems they just work with the Dokka base plugin and all the samples are located at Samples tab or Samples section for Jekyll plugin.

I didn't find an option to locate inline samples in the description. All the text after a sample is skipped.

And I didn't find a way to make it work with Arrow libraries (screenshot for Dokka base plugin):

Jekyll Plugin

Links

They work fine for Dokka Base Plugin. However, they don't have the right extension (.html) with Jekyll Plugin.

Before (Dokka 0.10.0):

title: arrow.core - arrow-core-data
---

[arrow-core-data](../index.html) / [arrow.core](./index.html)

## Package arrow.core

### Types

After:

title: arrow.core -
---
//[arrow-core-data](../index.md)/[arrow.core](index.md)



# Package arrow.core  


## Types  

It also appears // before every module.

Signatures

They appear at the end now.

Before (Dokka 0.10.0):

title: Option - arrow-core-data
---

[arrow-core-data](../../index.html) / [arrow.core](../index.html) / [Option](./index.html)

# Option

`@higherkind sealed class Option<out A> : OptionOf<A>`

If you have worked ...

After:

title: Option -
---
//[arrow-core-data](../../index.md)/[arrow.core](../index.md)/[Option](index.md)



# Option  
 [jvm] 



If you have worked ...


(...)


@[higherkind]()()  

sealed class [Option](index.md)<[A](index.md)> : [Kind]()<[ForOption](), [A](index.md)>    

I didn't find a way to remove the [jvm] text.

Styles

The use of ` is missing.

Before (Dokka 0.10.0):

`Option<A>` is a container for an optional value of type `A`.

After:

Option<A> is a container for an optional value of type A.

So there are several cases where <A> is used as the a HTML element.

It also impacts on inline code snippets with:

``` kotlin

Those directives disappear and code snippets don't have the right style then.

Tables

The whole description is shown instead of just the first paragraph:

Before (Dokka 0.10.0):

After:

[rachelcarmena]

Feedback from @sellmair about:

dependencies {
    dokkaJekyllPlugin("org.jetbrains.dokka:jekyll-plugin:$DOKKA_VERSION")
}

It's not necessary because it's automatically added.

[sellmair]

@kamildoleglo @MarcinAman @Kordyjan
There is some highly interesting feedback for us in this thread ☺️