gradle使用dokka插件出现Exception while loading package-list from ExternalDocumentationLinkImp

这是一个月多前遇到的问题,现在特做记录:

build.gradle.kts里配置了dokka插件的时候出现这个异常,Exception while loading package-list from ExternalDocumentationLinkImp

dokka是gradle的一个插件,功能类似与javadoc.对于这个异常当时看了好多博客也都不行,最终找到dokka的github的一个问题单:

https://github.com/Kotlin/dokka/issues/213#

当时一看,哇,还是open状态,看了别人的回复,对于这个问题结论是这样:

1.这个异常首先是因为请求一个网址,比如android.com去拿一个package-list时请求失败.而dokka需要这个package-list;

首先分析请求失败的原因:

　　1)你公司有一个外网访问限制(大部分问题来自于此)

　　2)GFW之类的

总之都是网络问题;

2.所以解决方法正如问题单所说的:

　　1)自己提供package-list 并做配置;比如这个开发者老哥说的:

Try again, or maybe you are behind the corporate proxy? 
Then you should manually download https://developer.android.com/reference/package-list, place it somewhere and use packageListUrl parameter to configure its location.

　　之前在问题单#213和dokka的github主页都看过这样的设置,也就是设置packageListUrl,指定自己给的package-list...不过我没试过.因为当时我的build.gradle用的是dokkaTask,也没找到配置方法.

dokka {
    outputFormat = 'html'
    outputDirectory = "$buildDir/javadoc"

    externalDocumentationLink {
        // Root URL of the generated documentation to link with. The trailing slash is required!
        url = new URL("http://github.com/me/myrepo")

        // If package-list file located in non-standard location
        packageListUrl = new URL("file:///D:/package-list")
    }
}

 

　　2)配置外网的代理Proxy:

　　具体方法是:

　　如果你的gradle的home都是默认的话,那在这个 .gradle目录下可以如此操作.

在本地C盘,用户/计算机名/.gradle 目录下创建一个 gradle.properties;
填上:
systemProp.http.proxyPort=eg.8080
systemProp.http.proxyUser=username
systemProp.http.proxyPassword=password
systemProp.http.nonProxyHosts=*.**.com, 10.* 正则配置
systemProp.http.proxyHost=***.**.com 之类
systemProp.https.proxyPort=8080
systemProp.https.proxyUser=username
systemProp.https.proxyPassword=password
systemProp.https.nonProxyHosts=*.**.com, 10.*
systemProp.https.proxyHost=**.**.com

这个文件的作用是在build前设置好系统变量,让gradle使用

　嗯,现在你应该能访问了,简单来说,就是让你连得上,能够请求,自然就成功了.

　 3)特殊情况:公司特别奇葩,配置了proxy也无法登陆那个网站

　　而且, 适用于现在只是想build,跳过doc生成也可以的情况.

　　那就是添加 noStdlibLink = true .这个设置类似于让它忽略doc输出时的错误,从而编译顺利执行.以某开源软件的代码为例:

tasks.withType(DokkaTask::class.java) {
        // suppresses undocumented classes but not dokka warnings
        // https://github.com/Kotlin/dokka/issues/229 && https://github.com/Kotlin/dokka/issues/319
        reportUndocumented = false
        outputFormat = "javadoc"
        outputDirectory = "$buildDir/javadoc"
         noStdlibLink = true //添加
    }

当时就是添加了这句就成功了.

不过这个异常遇到的人应该也不多,毕竟大部分人公司都有开放网络权限 : )