Dokka: To add an ability to disable link to java documentation

[neverov-test]

It would be great to disable link to java documentation, similar to noStdlibLink for Kotlin stdlib. Without that docs generation fails with the error like this when network is not available:

[ERROR] Failed to execute goal org.jetbrains.dokka:dokka-maven-plugin:0.9.15:dokka (default-cli) on project configs-dsl-kotlin: Execution default-cli of goal org.jetbrains.dokka:dokka-maven-plugin:0.9.15:dokka failed: Guice provision errors:
[ERROR]
[ERROR] 1) Error injecting constructor, java.lang.RuntimeException: Exception while loading package-list from ExternalDocumentationLinkImpl(url=http://docs.oracle.com/javase/6/docs/api/, packageListUrl=http://docs.oracle.com/javase/6/docs/api/package-list)
[ERROR] at org.jetbrains.dokka.ExternalDocumentationLinkResolver.<init>(ExternalDocumentationLinkResolver.kt:25)
[ERROR] at org.jetbrains.dokka.ExternalDocumentationLinkResolver.class(ExternalDocumentationLinkResolver.kt:25)
[ERROR] while locating org.jetbrains.dokka.ExternalDocumentationLinkResolver
[ERROR] for parameter 4 at org.jetbrains.dokka.DeclarationLinkResolver.<init>(DeclarationLinkResolver.kt:9)
[ERROR] while locating org.jetbrains.dokka.DeclarationLinkResolver
[ERROR] for parameter 0 at org.jetbrains.dokka.PackageDocs.<init>(PackageDocs.kt:13)
[ERROR] at org.jetbrains.dokka.PackageDocs.class(PackageDocs.kt:12)
[ERROR] while locating org.jetbrains.dokka.PackageDocs

[semoro]

See cacheRoot option of Dokka, it can cache package-lists and prevent you from failing when there is no network.

[nd]

As far as I understand, ExternalDocumentationLinkResolver always opens a connection to the package list url (when the cached entry exists, it checks the modified date) and will fail when there is no network.

[semoro]

It should show a warning, not fail when checking for modified date

[semoro]

There is a try catch https://github.com/Kotlin/dokka/blob/master/core/src/main/kotlin/Kotlin/ExternalDocumentationLinkResolver.kt#L63

[neverov-test]

The error is ignored only when cached package list exists. To make workaround with cacheRoot work one has to create files: <cacheRoot>/packageListCache/b0399cd2fcad6fbbe6e9418561d0bdeb49e9a9087f4b551eec9bd0bc2aab04b7 for http://docs.oracle.com/javase/6/docs/api/ and <cacheRoot>/packageListCache/2114a4473a8231ed72f4678ae4c050e37d7d6b1867aea87b956f30badcd4df09 for https://kotlinlang.org/api/latest/jvm/stdlib/. Without them task still fails with cacheRoot option.

[juergenzimmermann]

Is there an update for http://docs.oracle.com/javase/9/docs/api/package-list ?

[qualityking]

I am behind proxy but still can create Javadoc out of Pojo application, so what so special with kotlin that it is it not letting us generate javadoc.

[jacombo]

proxy support would be added by https://github.com/Kotlin/dokka/pull/314
it support with basic authentication has been added using system properties below

-Dhttp.proxyHost=host.domain.com
-Dhttp.proxyPort=8080
-Dhttps.proxyHost=host.domain.com
-Dhttps.proxyPort=8080
-DproxySet=true
-DproxyUser=user
-DproxyPassword=password

if proxySet is true and proxyUser with proxyPassword is set then basic proxy authentication is added

[stephenbyrne-mfj]

I think Dokka should not connect to the internet while building by default. I would rather see an option to enable stdlib links (that is disabled by default) than an option to disable stdlinks. But an option to disable stdlib links would be better than the current situation.

I think it is reasonable to expect that when building, the only internet connections made are those made by the build system to configured endpoints (e.g.: Maven and SCM as configured in the build scripts or user/system build tool configuration). I do builds on systems whose firewalls only allow connections to our maven repository and SCM server, and Dokka now makes builds fail.

[aminfara]

This is a major blocker in my team's adaptation of Kotlin. Our build system only builds artefacts in isolation.

I can see that 8e9e768 will solve this issue. Is there any plan to release this change?

[weickmanna]

We also stumbled into this issue quickly after adopting Kotlin. We would never have expected this plugin to connect to the internet, especially not by default.

[sellophane]

I can confirm this fix will be included in the upcoming release 0.9.18.

[robotsquidward]

What's the fix? I still get the same error with dokka going to the internet to get package-list. Is it just adding proxy config?

[kamildoleglo]

There is a configuration option noJdkLink

[robotsquidward]

Thanks, I did end up getting it working (for Android) with this config.

    dokka {
        outputFormat = 'html'
        outputDirectory = "$buildDir/docs"
        configuration {
            externalDocumentationLink {
                // We can't link to external resources for source, so disable linking and
                // set a local file url for package lists.
                noJdkLink = true
                noStdlibLink = true
                noAndroidSdkLink = true
                url = new URL("https://developer.android.com/reference/")
                packageListUrl = new URL("file:///${rootDir}/package-list")
            }
        }
    }