Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Allow customizing Dokka options #222

Closed
tadfisher opened this issue Jan 12, 2019 · 4 comments
Closed

Allow customizing Dokka options #222

tadfisher opened this issue Jan 12, 2019 · 4 comments
Projects

Comments

@tadfisher
Copy link

@tadfisher tadfisher commented Jan 12, 2019

Right now, the repositories used for dependency resolution by dokka-json are fixed, so it doesn't look like we can, for example, add https://maven.google.com/ to resolve Android artifacts.

It would also be nice to be able to specify other Dokka options, such as the source roots to include or the Kotlin tasks to analyze.

@cjbrooks12

This comment has been minimized.

Copy link
Contributor

@cjbrooks12 cjbrooks12 commented Jan 12, 2019

The KotlinDoc plugin isn't connected to your Gradle build, it is intended to be run completely independent of Gradle or any other build tool. Unfortunately, this does mean that it is limited in how it runs, not having knowledge of Gradle's sourcesets, dependencies, and tasks, but also means there's really no need to include other package repositories in the Dokka run.

But you are able to customize the source roots to analyze, with the kotlindoc. sourceDirs property in your config.yml, which accepts a list of file paths relative to your Orchid site resources dir:

# config.yml
...
kotlindoc:
  sourceDirs: 
    - '../../main/kotlin'

That being said, Dokka does have some issues when referencing classes not in the stdlib or in the sources being analyzed. The intention is that the docs will still work when referencing these classes and they just won't be linkable, but they are currently showing up empty. I will have to investigate this further.

@tadfisher

This comment has been minimized.

Copy link
Author

@tadfisher tadfisher commented Jan 12, 2019

Unfortunately, this does mean that it is limited in how it runs, not having knowledge of Gradle's sourcesets, dependencies, and tasks, but also means there's really no need to include other package repositories in the Dokka run.

Understandable, but perhaps it would be possible to supply a classpath to the plugin, and the Gradle integration could infer these values from the project?

The intention is that the docs will still work when referencing these classes and they just won't be linkable, but they are currently showing up empty.

This is because Dokka takes an additional "classpath" parameter that is used for resolving types in dependency jars: https://github.com/Kotlin/dokka#using-the-command-line

I don't believe the Kotlindoc plugin is supplying this parameter, thus Dokka outputs <ERROR CLASS> (at least in its Markdown/HTML output) for the unknown types.

@cjbrooks12 cjbrooks12 added this to Triage in Backlog via automation Jan 14, 2019
@cjbrooks12 cjbrooks12 moved this from Triage to In Progress in Backlog Jan 14, 2019
@cjbrooks12

This comment has been minimized.

Copy link
Contributor

@cjbrooks12 cjbrooks12 commented Jan 14, 2019

I have the plugin passing the classpath through to Dokka. I am releasing it now, it will be available in 0.15.3 later today. There is a new --kotlindocClasspath arg that you can pass to Orchid, which gets passed-through directly to Dokka's -classpath arg.

Here's how it would look in Gradle:

afterEvaluate { // I was getting Gradle errors unless the `orchid` closure was in `afterEvaluate`
    orchid {
        ...
        args = [
            "--kotlindocClasspath", // the new Orchid arg
            project(":app").sourceSets.main.runtimeClasspath.getAsPath() // use Gradle APIs to get the classpath to pass-through
        ]
    }
}
@cjbrooks12

This comment has been minimized.

Copy link
Contributor

@cjbrooks12 cjbrooks12 commented Jan 14, 2019

0.15.3 is now available, please try it out and let me know how it works! Here are the updated docs

@cjbrooks12 cjbrooks12 closed this Jan 24, 2019
Backlog automation moved this from In Progress to Waiting for Release Jan 24, 2019
@cjbrooks12 cjbrooks12 moved this from Waiting for Release to Done in Backlog Jan 25, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
Backlog
  
Done
2 participants
You can’t perform that action at this time.