Problems running dokka-cli-1.4.0-rc.jar from the command line

Are there any examples available for running dokka-cli-1.4.0-rc.jar from the command line (especially for Windows 10)? I was able to get dokka-fatjar-0.10.1.jar working without too much trouble, but I tried multiple variations for dokka-cli-1.4.0-rc.jar without success. I was getting an “Access is denied.” error at one point. Here is my latest version and the response.

java -jar C:\kotlin\Dokka\dokka-cli-1.4.0-rc.jar -outputDir C:\JMooreMACS\Teaching\Compiler\dokka -sourceSet -moduleName Compiler -src C:\JMooreMACS\Teaching\Compiler\Projects\Compiler\src

Exception in thread “main” java.lang.IllegalStateException: No value for option -moduleName

Also, is there an easy way to generate Kotlin documentation (html files) from IntelliJ IDEA. What I am looking for is a Kotlin equivalent to the “Generate JavaDoc” tool command.

Hi,

thank you for your submission. The problem is in the way you declare arguments. Though your input would work on older dokka, new one is using kotlinx.cli for parameters parsing. Because kotlinx.cli is lacking mechanism allowing nested parameters, you have to provide all parameters with values as a single argument for -sourceSet. The only way to obtain that is to enclose your arguments in "", so for your case it would go -sourceSet "-moduleName Compiler -src C:\JMooreMACS\Teaching\Compiler\Projects\Compiler\src". Of course you can chain many source sets in the same manner e. g. -sourceSet "..." -sourceSet "..." .... I know it’s not clearly stated in README manual, we will fix it as soon as possible and sorry for your inconvenience.

However, your configuration is not exhaustive yet. New dokka decoupled default documentation templating etc from the engine, therefore you have to provide it manually yourself. All you need is dokka-base, which is published as dokka-base.jar. You can add it using -pluginsClasspath parameter. Note you have to provide all required classpath dependencies e. g. kotlinx.html in order to work.

Unfortunately, currently there is a problem with loading one of such dependencies classpath: kotlin-analysis.jar. You can subscribe to this issue to get notified about current state on that bug https://github.com/Kotlin/dokka/issues/1364

If you have any further questions, feel free to ask

Hi again,

because of my miscommunication I wrongly diagnosed it as a bug. In fact I just didn’t load all the dependencies. Here I list the dependencies you need run dokka from CLI. I will update README soon, to notify future users. You need:

So, in your case, the correct input is given:
java -jar C:\kotlin\Dokka\dokka-cli-1.4.0-rc.jar -outputDir C:\JMooreMACS\Teaching\Compiler\dokka -pluginsClasspath "dokka-base-1.4.0-rc.jar;dokka-analysis-1.4.0-rc.jar;kotlin-analysis-compiler-1.4.0-rc.jar;kotlin-analysis-intellij-1.4.0-rc.jar;kotlinx-coroutines-core-1.3.9.jar;kotlinx-html-jvm-0.7.2.jar" -sourceSet "-moduleName Compiler -src C:\JMooreMACS\Teaching\Compiler\Projects\Compiler\src"

Please, let me know if it runs correctly

Thanks so much for your help, but this still does not work for me. Evidently this version can’t seem to find the plugins. I searched my hard drive, and I couldn’t find them either. Then I searched the internet and found them, but not all in one place. I downloaded the jar files, but I can’t figure out how to make them available on my “pluginsClasspath”. Simply adding the jar files to the CLASSPATH did not work.

I would really like to be able to run dokka to generate kotlin documentation directly from the command line. But if there isn’t an easy way to do that, I will settle for a way to do it directly from IntelliJ IDEA. As I said in my original post, I was able to get dokka-fatjar-0.10.1.jar working without too much trouble.

But beyond my personal issues at the moment with dokka, I would like to request a simple, easy-to-use, well-documented tool/capability for generating Kotlin documentation files. With Java we have Javadoc. So far I don’t see anything close that for Kotlin.

The elements in the dependency list I attached in my previous reply are hyperlinks that are pointing to maven central so you can get them from right source. You provide them either by absolute or relative path. I wrote relative path as I assumed you would put all the files in one directory then run them from terminal which is opened in that directory. So in order to make the CLI working try changing all -pluginClasspath jars to be absolute paths or if you decide to put all 7 jars (dokka-cli.jar and its 6 dependencies) in one directory, I believe that running java -jar dokka-cli-1.4.0-rc.jar ... from that path will work successfully.

The idea behind dokka in version 1.4 is to modularize engine and allow users write custom plugins. We decided to no longer ship fatjar for CLI, becuase user can have his own extension, that has no common part with base-plugin thus will have no use of its default implementations for extension points. This is done by design

I am really sorry you have bad thoughts about new dokka. I’m looking forward to get feedback if it is working now as expected

1 Like

Thank you. That works. I used absolute path names for each plugin. Actually I used variables and put everything into a script (command) file. And I had no trouble adding additional source sets.

And I understand your reasoning behind the new design of dokka. I just don’t agree with it. It reminds me programmers years ago that would have 20 or 30 parameters for a function to make it completely flexible.

1 Like

One additional point now that I examine the result. I have a class comment that reads as follows:

/**
 * The abstract syntax tree node for a multiplying expression.  A multiplying
 * expression is a binary expression where the operator is a multiplying operator
 * such as "*", "/", or "mod".  A simple example would be "5*x".
 */

But the output from dokka totally messes up the last part. Here is what I get from dokka:

The abstract syntax tree node for a multiplying expression. A multiplying expression is a binary expression where the operator is a multiplying operator such as "x".

Any suggestions? The result might be related to something with markdown. I know a lot about html, but I am less familiar with markdown.

That is very interesting. The single asterisk mark * is used in markdown to make the text italic by surrounding the text sequence with them, for example *i want this text to be italic*. Nonetheless, in your case it rips the body between asterisk instead making it at least italic (though it should stay untouched as there is no whitespace before and after the asterisk). Probably, it’s not our fault per se as we use this dependency for parsing markdown, if so, I cannot estimate how long does it take to fix this bug. I’ll debug it for you on Monday so please be patient.

I am also glad that you made the dokka going and I hope you enjoy new design

Maybe try backslashing both asterisks? I.e. like this “\*”

I tried escaping but apparently it is not handled correctly by the parsing library, because it renders with backslashes e. g. as "\*", "/", or "mod". A simple example would be "5\*x".

1 Like

Thanks again for looking into this. I have one more bit of feedback for you before you start to debug it. If I replace only the second asterisk (*) by mod, then everything works fine, as in

... multiplying operator such as "*", "/", or "mod". A simple example would be "5 mod x".

Apparently it has something to do with the fact that there are two asterisks in that comment.

1 Like

Hi,

I did some investigation on that case. According to GfmMarkdownFlavour which dokka uses there is specification when asterisk classifies as an token for opening/closing sequence of italic text. So in your case it should indeed be italic. I fixed this behaviour in this PR. I hope it will get merged and published soon.

As it comes to escaping asterisk with backslash there is probably bug in markdown parser library. I contacted with its creator, so we can sort it out. If I get know more about that specific problem I will let you know.

1 Like

Thank you. I truly appreciate you help and diligence with this issue.

I encountered another related issue that you should be aware of. Dokka Alpha for Kotlin 1.4 has been released, but there does not seem to be a valid link to the Dokka CLI runner. Both https://github.com/Kotlin/dokka and https://kotlin.github.io/dokka/1.4.0/user_guide/cli/usage/ have links to the Dokka CLI runner, but both links yield 404 (not found) errors. I finally found it here: https://github.com/Kotlin/dokka/releases

1 Like

Thank you again for your assistance. We will fix it as soon as possible.

As it comes to escaping the asterisk in markdown, I know that author of markdown parser dependency is aware of this bug, however I don’t know the current state of progress towards amendment. I’ll write you here when we will know more.

Out of curiosity, is there a reason to use dokka-cli instead of dokka-fatjar?

Because we no longer support fatjar in version 1.4. The latest version supporting fatjar was 0.10.2, but since that time, dokka has been completely rewritten from scratch.

We dropped fatjar, as new dokka focuses on plugins. Even the default behaviour is considered as a plugin (dokka-base). Therefore, we decided that user has to provide plugins and thier dependencies on his own. Of course, using gradle plugin of dokka manages a lot of these for user. CLI, on the other hand cannot assist in resolving dependencies.

Thank you for the quick reply. I wish to second @softmoore’s remarks on usability (it works from the command line, but crashes in Idea). For the command line, the online documentation is very confusing, and has no examples. Examples would be nice, especially if they show how to use it.

What do you mean ‘craches from idea’? Maybe you could file the issue at github repository Kotlin/dokka providing more info on that case?

We will add more examples to the manual, as I see there is a big interest in CLI.

What do you ‘craches from idea’?

“Briefly”, I get this when I run this in Idea using Gradle:

$ ./gradlew --stacktrace dokkaHtml
[stuff omttied]
> Task :dokkaHtml FAILED

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':dokkaHtml'.
> kotlin.jvm.internal.Reflection.typeOf(Ljava/lang/Class;)Lkotlin/reflect/KType;

* Try:
Run with --info or --debug option to get more log output. Run with --scan to get full insights.

* Exception is:
org.gradle.api.tasks.TaskExecutionException: Execution failed for task ':dokkaHtml'.
    at org.gradle.api.internal.tasks.execution.ExecuteActionsTaskExecuter$2.accept(ExecuteActionsTaskExecuter.java:121)
    at org.gradle.api.internal.tasks.execution.ExecuteActionsTaskExecuter$2.accept(ExecuteActionsTaskExecuter.java:117)
    at org.gradle.internal.Try$Failure.ifSuccessfulOrElse(Try.java:184)
[more stuff deleted]

I wanted to look into this more before I file a bug report. If nothing else, I’d start a new thread in this forum.

Maybe you could file the issue at github repository Kotlin/dokka providing more info on that case?

Sometimes I can figure out what’s wrong, and on occasion it’s my fault. Often if I figure a workaround (e.g., command line) I just don’t worry about it. However, I’ll file an issue if need be.