Upgrade to Dokka 1.5-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 Kotlin/dokka#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!! 🙌 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 Kotlin/dokka#1194 continues being a draft so it seems the proposed changes here are still valid 🙌

[rachelcarmena]

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

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 ☺️

[rachelcarmena]

Update: all these issues with dokkaJekyll still happen when using Dokka 1.4.31 so it's not possible to do the upgrade.

On the other hand, there is an issue with the current version 0.10.0 because it depends on jCenter for org.jetbrains.dokka.gradle.DokkaTask.tryResolveFatJar and that repository has a sunset date. However, that's solved in 0.10.1.

[rachelcarmena]

The dependency is also fixed for 0.10.0 (I suppose Kotlin replicated the artifacts in that repository because of the sunset).

[rachelcarmena]

I created these issues in dokka repository a few days ago:

• [Jekyll Plugin] Links with .md extension instead of .html
• [Jekyll Plugin] Missing code format

[nomisRev]

Thank you @rachelcarmena!

[nomisRev]

Closed due to upgraded to Dokka 1.5.0 🥳

[rachelcarmena]

Hi friends!! So worry 🙏 I think there are still issues with Dokka 1.5.0. For instance:

• Latest release: https://arrow-kt.io/docs/apidocs/arrow-fx-stm/arrow.fx.stm/stm.html
• Next version: https://arrow-kt.io/docs/next/apidocs/arrow-fx-stm/arrow.fx.stm/stm.html

And Docs links on the menu are broken now. For instance:

• Latest version: https://arrow-kt.io/docs/apidocs/arrow-core/
• Next version: https://arrow-kt.io/docs/next/apidocs/arrow-core/

[nomisRev]

Hey @rachelcarmena,
Thanks for raising this issue! 🙏

Looks like on the STM pages some CSS classes dissapeared and it loses it styling 🤔

Weird I ran Isra's branch locally, and it looked fine. Also these STM pages you linked.
I will run it locally again, and I'll contact the Dokka team.

I'll keep you posted here 👍

[nomisRev]

@rachelcarmena Will have to revert back to 0.10.x :(
Thanks for raising this! 🙌

[rachelcarmena]

Hi @nomisRev 🙌

I created 2 issues:

• [Jekyll Plugin] Links with .md extension instead of .html
• [Jekyll Plugin] Missing code format

The first one was solved and included in Dokka 1.5.0.

The second one is still open and it's related to that format issue.

I think they are waiting for more people who are interested on Dokka + Jekyll because the first issue was inmediately solved as soon as another person wrote a comment there.

About the broken links on the sidebar menu for API documentation, some ideas:

• Maybe the generated HTML for API doc has a different organization and it's necessary to adapt the links.
• Or the Jekyll pages aren't being generated (so HTML pages will be missing as well). Dokka configuration could be involved.

Just sharing a global view to help:

1. Gradle task dokkaJekyll

• It generates .md files from API documentation.
• According to the configuration for API doc creation, all the generated .md files will be located into arrow-site/docs/apidocs.

2. Gradle task runAnk

• According to Ank configuration, Ank validation will process arrow-site/docs and will generate arrow-site/build/site.

3. Jekyll build bundle exec jekyll serve -s build/site

• It generates HTML pages from .md files. Default output directory: _site.

[nomisRev]

Hey @rachelcarmena 🙌 ,
Thanks for the update 🙏

I think all links are fixed, and the described issues are fixed here: https://github.com/arrow-kt/arrow/tree/testing-web-update
Based on efforts which started here: #246

I think the html instead of md links are still broken in some places, thanks for brining this up.

The code fences have been fixed, and so have the code blocks.

[rachelcarmena]

Awesome, huge congrats @nomisRev !!! 👏 👏 👏

In case you'd like to avoid the creation of another bucket, here the configuration that I used on Netlify:

• Build command: cd arrow-libs; ./gradlew dokka; cd ../arrow-site; ./gradlew runAnk; bundle install --gemfile Gemfile --path vendor/bundle; bundle exec jekyll build -s build/site
• Publish directory: arrow-site/_site

[i-walker]

We've already upgraded Dokka to 1.6.X :D
going to close this