484 lines
19 KiB
Markdown
484 lines
19 KiB
Markdown
dokka
|
|
=====
|
|
|
|
**_Note_: This is Google's fork of Dokka, customized for [Android API reference docs](https://developer.android.com/reference/)
|
|
on [developer.android.com](https://developer.android.com/) and other Google products.**
|
|
|
|
Dokka is a documentation engine for Kotlin, performing the same function as javadoc for Java.
|
|
Just like Kotlin itself, Dokka fully supports mixed-language Java/Kotlin projects. It understands
|
|
standard Javadoc comments in Java files and [KDoc comments](https://kotlinlang.org/docs/reference/kotlin-doc.html) in Kotlin files,
|
|
and can generate documentation in multiple formats including standard Javadoc, HTML and Markdown.
|
|
|
|
## Using Dokka
|
|
|
|
### Using the Gradle plugin
|
|
|
|
```groovy
|
|
buildscript {
|
|
repositories {
|
|
jcenter()
|
|
}
|
|
|
|
dependencies {
|
|
classpath "org.jetbrains.dokka:dokka-gradle-plugin:${dokka_version}"
|
|
}
|
|
}
|
|
|
|
apply plugin: 'org.jetbrains.dokka'
|
|
```
|
|
|
|
The plugin adds a task named "dokka" to the project.
|
|
|
|
Minimal dokka configuration:
|
|
|
|
```groovy
|
|
dokka {
|
|
outputFormat = 'html'
|
|
outputDirectory = "$buildDir/javadoc"
|
|
}
|
|
```
|
|
|
|
[Output formats](#output_formats)
|
|
|
|
The available configuration options are shown below:
|
|
|
|
```groovy
|
|
dokka {
|
|
moduleName = 'data'
|
|
outputFormat = 'html'
|
|
outputDirectory = "$buildDir/javadoc"
|
|
|
|
// These tasks will be used to determine source directories and classpath
|
|
kotlinTasks {
|
|
defaultKotlinTasks() + [':some:otherCompileKotlin', project("another").compileKotlin]
|
|
}
|
|
|
|
// List of files with module and package documentation
|
|
// http://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation
|
|
includes = ['packages.md', 'extra.md']
|
|
|
|
// The list of files or directories containing sample code (referenced with @sample tags)
|
|
samples = ['samples/basic.kt', 'samples/advanced.kt']
|
|
|
|
jdkVersion = 6 // Used for linking to JDK
|
|
|
|
// Use default or set to custom path to cache directory
|
|
// to enable package-list caching
|
|
// When set to default, caches stored in $USER_HOME/.cache/dokka
|
|
cacheRoot = 'default'
|
|
|
|
// Use to include or exclude non public members.
|
|
includeNonPublic = false
|
|
|
|
// Do not output deprecated members. Applies globally, can be overridden by packageOptions
|
|
skipDeprecated = false
|
|
|
|
// Emit warnings about not documented members. Applies globally, also can be overridden by packageOptions
|
|
reportUndocumented = true
|
|
|
|
skipEmptyPackages = true // Do not create index pages for empty packages
|
|
|
|
impliedPlatforms = ["JVM"] // See platforms section of documentation
|
|
|
|
// Manual adding files to classpath
|
|
// This property not overrides classpath collected from kotlinTasks but appends to it
|
|
classpath = [new File("$buildDir/other.jar")]
|
|
|
|
// By default, sourceRoots is taken from kotlinTasks, following roots will be appended to it
|
|
// Short form sourceRoots
|
|
sourceDirs = files('src/main/kotlin')
|
|
|
|
// By default, sourceRoots is taken from kotlinTasks, following roots will be appended to it
|
|
// Full form sourceRoot declaration
|
|
// Repeat for multiple sourceRoots
|
|
sourceRoot {
|
|
// Path to source root
|
|
path = "src"
|
|
// See platforms section of documentation
|
|
platforms = ["JVM"]
|
|
}
|
|
|
|
// Specifies the location of the project source code on the Web.
|
|
// If provided, Dokka generates "source" links for each declaration.
|
|
// Repeat for multiple mappings
|
|
linkMapping {
|
|
// Source directory
|
|
dir = "src/main/kotlin"
|
|
|
|
// URL showing where the source code can be accessed through the web browser
|
|
url = "https://github.com/cy6erGn0m/vertx3-lang-kotlin/blob/master/src/main/kotlin"
|
|
|
|
// Suffix which is used to append the line number to the URL. Use #L for GitHub
|
|
suffix = "#L"
|
|
}
|
|
|
|
// No default documentation link to kotlin-stdlib
|
|
noStdlibLink = false
|
|
|
|
// Allows linking to documentation of the project's dependencies (generated with Javadoc or Dokka)
|
|
// Repeat for multiple links
|
|
externalDocumentationLink {
|
|
// Root URL of the generated documentation to link with. The trailing slash is required!
|
|
url = new URL("https://example.com/docs/")
|
|
|
|
// If package-list file located in non-standard location
|
|
// packageListUrl = new URL("file:///home/user/localdocs/package-list")
|
|
}
|
|
|
|
// Allows to customize documentation generation options on a per-package basis
|
|
// Repeat for multiple packageOptions
|
|
packageOptions {
|
|
prefix = "kotlin" // will match kotlin and all sub-packages of it
|
|
// All options are optional, default values are below:
|
|
skipDeprecated = false
|
|
reportUndocumented = true // Emit warnings about not documented members
|
|
includeNonPublic = false
|
|
}
|
|
// Suppress a package
|
|
packageOptions {
|
|
prefix = "kotlin.internal" // will match kotlin.internal and all sub-packages of it
|
|
suppress = true
|
|
}
|
|
}
|
|
```
|
|
|
|
To generate the documentation, use the `dokka` Gradle task:
|
|
|
|
```bash
|
|
./gradlew dokka
|
|
```
|
|
|
|
More dokka tasks can be added to a project like this:
|
|
|
|
```groovy
|
|
task dokkaJavadoc(type: org.jetbrains.dokka.gradle.DokkaTask) {
|
|
outputFormat = 'javadoc'
|
|
outputDirectory = "$buildDir/javadoc"
|
|
}
|
|
```
|
|
|
|
Please see the [Dokka Gradle example project](https://github.com/JetBrains/kotlin-examples/tree/master/gradle/dokka-gradle-example) for an example.
|
|
|
|
#### Android
|
|
|
|
If you are using Android there is a separate Gradle plugin. Just make sure you apply the plugin after
|
|
`com.android.library` and `kotlin-android`.
|
|
|
|
```groovy
|
|
buildscript {
|
|
repositories {
|
|
jcenter()
|
|
}
|
|
|
|
dependencies {
|
|
classpath "org.jetbrains.dokka:dokka-android-gradle-plugin:${dokka_version}"
|
|
}
|
|
}
|
|
|
|
apply plugin: 'com.android.library'
|
|
apply plugin: 'kotlin-android'
|
|
apply plugin: 'org.jetbrains.dokka-android'
|
|
```
|
|
|
|
### Using the Maven plugin
|
|
|
|
The Maven plugin is available in JCenter. You need to add the JCenter repository to the list of plugin repositories if it's not there:
|
|
|
|
```xml
|
|
<pluginRepositories>
|
|
<pluginRepository>
|
|
<id>jcenter</id>
|
|
<name>JCenter</name>
|
|
<url>https://jcenter.bintray.com/</url>
|
|
</pluginRepository>
|
|
</pluginRepositories>
|
|
```
|
|
|
|
Minimal Maven configuration is
|
|
|
|
```xml
|
|
<plugin>
|
|
<groupId>org.jetbrains.dokka</groupId>
|
|
<artifactId>dokka-maven-plugin</artifactId>
|
|
<version>${dokka.version}</version>
|
|
<executions>
|
|
<execution>
|
|
<phase>pre-site</phase>
|
|
<goals>
|
|
<goal>dokka</goal>
|
|
</goals>
|
|
</execution>
|
|
</executions>
|
|
</plugin>
|
|
```
|
|
|
|
By default files will be generated in `target/dokka`.
|
|
|
|
The following goals are provided by the plugin:
|
|
|
|
* `dokka:dokka` - generate HTML documentation in Dokka format (showing declarations in Kotlin syntax);
|
|
* `dokka:javadoc` - generate HTML documentation in JavaDoc format (showing declarations in Java syntax);
|
|
* `dokka:javadocJar` - generate a .jar file with JavaDoc format documentation.
|
|
|
|
The available configuration options are shown below:
|
|
|
|
```xml
|
|
<plugin>
|
|
<groupId>org.jetbrains.dokka</groupId>
|
|
<artifactId>dokka-maven-plugin</artifactId>
|
|
<version>${dokka.version}</version>
|
|
<executions>
|
|
<execution>
|
|
<phase>pre-site</phase>
|
|
<goals>
|
|
<goal>dokka</goal>
|
|
</goals>
|
|
</execution>
|
|
</executions>
|
|
<configuration>
|
|
|
|
<!-- Set to true to skip dokka task, default: false -->
|
|
<skip>false</skip>
|
|
|
|
<!-- Default: ${project.artifactId} -->
|
|
<moduleName>data</moduleName>
|
|
<!-- See list of possible formats below -->
|
|
<outputFormat>html</outputFormat>
|
|
<!-- Default: ${project.basedir}/target/dokka -->
|
|
<outputDir>some/out/dir</outputDir>
|
|
|
|
<!-- Use default or set to custom path to cache directory to enable package-list caching. -->
|
|
<!-- When set to default, caches stored in $USER_HOME/.cache/dokka -->
|
|
<cacheRoot>default</cacheRoot>
|
|
|
|
<!-- List of '.md' files with package and module docs -->
|
|
<!-- http://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation -->
|
|
<includes>
|
|
<file>packages.md</file>
|
|
<file>extra.md</file>
|
|
</includes>
|
|
|
|
<!-- List of sample roots -->
|
|
<samplesDirs>
|
|
<dir>src/test/samples</dir>
|
|
</samplesDirs>
|
|
|
|
<!-- Used for linking to JDK, default: 6 -->
|
|
<jdkVersion>6</jdkVersion>
|
|
|
|
<!-- Do not output deprecated members, applies globally, can be overridden by packageOptions -->
|
|
<skipDeprecated>false</skipDeprecated>
|
|
<!-- Emit warnings about not documented members, applies globally, also can be overridden by packageOptions -->
|
|
<reportNotDocumented>true</reportNotDocumented>
|
|
<!-- Do not create index pages for empty packages -->
|
|
<skipEmptyPackages>true</skipEmptyPackages>
|
|
|
|
<!-- See platforms section of documentation -->
|
|
<impliedPlatforms>
|
|
<platform>JVM</platform>
|
|
</impliedPlatforms>
|
|
|
|
<!-- Short form list of sourceRoots, by default, set to ${project.compileSourceRoots} -->
|
|
<sourceDirectories>
|
|
<dir>src/main/kotlin</dir>
|
|
</sourceDirectories>
|
|
|
|
<!-- Full form list of sourceRoots -->
|
|
<sourceRoots>
|
|
<root>
|
|
<path>src/main/kotlin</path>
|
|
<!-- See platforms section of documentation -->
|
|
<platforms>JVM</platforms>
|
|
</root>
|
|
</sourceRoots>
|
|
|
|
<!-- Specifies the location of the project source code on the Web. If provided, Dokka generates "source" links
|
|
for each declaration. -->
|
|
<sourceLinks>
|
|
<link>
|
|
<!-- Source directory -->
|
|
<dir>${project.basedir}/src/main/kotlin</dir>
|
|
<!-- URL showing where the source code can be accessed through the web browser -->
|
|
<url>http://github.com/me/myrepo</url>
|
|
<!--Suffix which is used to append the line number to the URL. Use #L for GitHub -->
|
|
<urlSuffix>#L</urlSuffix>
|
|
</link>
|
|
</sourceLinks>
|
|
|
|
<!-- No default documentation link to kotlin-stdlib -->
|
|
<noStdlibLink>false</noStdlibLink>
|
|
|
|
<!-- Allows linking to documentation of the project's dependencies (generated with Javadoc or Dokka) -->
|
|
<externalDocumentationLinks>
|
|
<link>
|
|
<!-- Root URL of the generated documentation to link with. The trailing slash is required! -->
|
|
<url>https://example.com/docs/</url>
|
|
<!-- If package-list file located in non-standard location -->
|
|
<!-- <packageListUrl>file:///home/user/localdocs/package-list</packageListUrl> -->
|
|
</link>
|
|
</externalDocumentationLinks>
|
|
|
|
<!-- Allows to customize documentation generation options on a per-package basis -->
|
|
<perPackageOptions>
|
|
<packageOptions>
|
|
<!-- Will match kotlin and all sub-packages of it -->
|
|
<prefix>kotlin</prefix>
|
|
|
|
<!-- All options are optional, default values are below: -->
|
|
<skipDeprecated>false</skipDeprecated>
|
|
<!-- Emit warnings about not documented members -->
|
|
<reportUndocumented>true</reportUndocumented>
|
|
<includeNonPublic>false</includeNonPublic>
|
|
</packageOptions>
|
|
</perPackageOptions>
|
|
</configuration>
|
|
</plugin>
|
|
```
|
|
|
|
Please see the [Dokka Maven example project](https://github.com/JetBrains/kotlin-examples/tree/master/maven/dokka-maven-example) for an example.
|
|
|
|
[Output formats](#output_formats)
|
|
|
|
### Using the Ant task
|
|
|
|
The Ant task definition is also contained in the dokka-fatjar.jar referenced above. Here's an example of using it:
|
|
|
|
```xml
|
|
<project name="Dokka" default="document">
|
|
<typedef resource="dokka-antlib.xml" classpath="dokka-fatjar.jar"/>
|
|
|
|
<target name="document">
|
|
<dokka src="src" outputdir="doc" modulename="myproject"/>
|
|
</target>
|
|
</project>
|
|
```
|
|
|
|
The Ant task supports the following attributes:
|
|
|
|
* `outputDir` - the output directory where the documentation is generated
|
|
* `outputFormat` - the output format (see the list of supported formats above)
|
|
* `classpath` - list of directories or .jar files to include in the classpath (used for resolving references)
|
|
* `samples` - list of directories containing sample code (documentation for those directories is not generated but declarations from them can be referenced using the `@sample` tag)
|
|
* `moduleName` - the name of the module being documented (used as the root directory of the generated documentation)
|
|
* `include` - names of files containing the documentation for the module and individual packages
|
|
* `skipDeprecated` - if set, deprecated elements are not included in the generated documentation
|
|
* `jdkVersion` - version for linking to JDK
|
|
* `impliedPlatforms` - See [platforms](#platforms) section
|
|
* `<sourceRoot path="src" platforms="JVM" />` - analogue of src, but allows to specify [platforms](#platforms)
|
|
* `<packageOptions prefix="kotlin" includeNonPublic="false" reportUndocumented="true" skipDeprecated="false"/>` -
|
|
Per package options for package `kotlin` and sub-packages of it
|
|
* `noStdlibLink` - No default documentation link to kotlin-stdlib
|
|
* `<externalDocumentationLink url="https://example.com/docs/" packageListUrl="file:///home/user/localdocs/package-list"/>` -
|
|
linking to external documentation, packageListUrl should be used if package-list located not in standard location
|
|
* `cacheRoot` - Use `default` or set to custom path to cache directory to enable package-list caching. When set to `default`, caches stored in $USER_HOME/.cache/dokka
|
|
|
|
|
|
### Using the Command Line
|
|
|
|
To run Dokka from the command line, download the [Dokka jar](https://github.com/Kotlin/dokka/releases/download/0.9.10/dokka-fatjar.jar).
|
|
To generate documentation, run the following command:
|
|
|
|
java -jar dokka-fatjar.jar <source directories> <arguments>
|
|
|
|
Dokka supports the following command line arguments:
|
|
|
|
* `-output` - the output directory where the documentation is generated
|
|
* `-format` - the [output format](#output-formats):
|
|
* `-classpath` - list of directories or .jar files to include in the classpath (used for resolving references)
|
|
* `-samples` - list of directories containing sample code (documentation for those directories is not generated but declarations from them can be referenced using the `@sample` tag)
|
|
* `-module` - the name of the module being documented (used as the root directory of the generated documentation)
|
|
* `-include` - names of files containing the documentation for the module and individual packages
|
|
* `-nodeprecated` - if set, deprecated elements are not included in the generated documentation
|
|
* `-impliedPlatforms` - List of implied platforms (comma-separated)
|
|
* `-packageOptions` - List of package options in format `prefix,-deprecated,-privateApi,+warnUndocumented;...`
|
|
* `-links` - External documentation links in format `url^packageListUrl^^url2...`
|
|
* `-noStdlibLink` - Disable documentation link to stdlib
|
|
* `-cacheRoot` - Use `default` or set to custom path to cache directory to enable package-list caching. When set to `default`, caches stored in $USER_HOME/.cache/dokka
|
|
|
|
|
|
### Output formats<a name="output_formats"></a>
|
|
|
|
* `html` - minimalistic html format used by default
|
|
* `javadoc` - Dokka mimic to javadoc
|
|
* `html-as-java` - as `html` but using java syntax
|
|
* `markdown` - Markdown structured as `html`
|
|
* `gfm` - GitHub flavored markdown
|
|
* `jekyll` - Jekyll compatible markdown
|
|
* `kotlin-website*` - internal format used for documentation on [kotlinlang.org](https://kotlinlang.org)
|
|
|
|
### Platforms<a name="platforms"></a>
|
|
|
|
Dokka can annotate elements with special `platform` block with platform requirements
|
|
|
|
Example of usage can be found on [kotlinlang.org](https://kotlinlang.org/api/latest/jvm/stdlib/)
|
|
|
|
Each source root has a list of platforms for which members are suitable.
|
|
Also, the list of 'implied' platforms is passed to Dokka.
|
|
If a member is not available for all platforms in the implied platforms set, its documentation will show
|
|
the list of platforms for which it's available.
|
|
|
|
## Dokka Internals
|
|
|
|
### Documentation Model
|
|
|
|
Dokka uses Kotlin-as-a-service technology to build `code model`, then processes it into `documentation model`.
|
|
`Documentation model` is graph of items describing code elements such as classes, packages, functions, etc.
|
|
|
|
Each node has semantic attached, e.g. Value:name -> Type:String means that some value `name` is of type `String`.
|
|
|
|
Each reference between nodes also has semantic attached, and there are three of them:
|
|
|
|
1. Member - reference means that target is member of the source, form tree.
|
|
2. Detail - reference means that target describes source in more details, form tree.
|
|
3. Link - any link to any other node, free form.
|
|
|
|
Member & Detail has reverse Owner reference, while Link's back reference is also Link.
|
|
|
|
Nodes that are Details of other nodes cannot have Members.
|
|
|
|
### Rendering Docs
|
|
|
|
When we have documentation model, we can render docs in various formats, languages and layouts. We have some core services:
|
|
|
|
* FormatService -- represents output format
|
|
* LocationService -- represents folder and file layout
|
|
* SignatureGenerator -- represents target language by generating class/function/package signatures from model
|
|
|
|
Basically, given the `documentation` as a model, we do this:
|
|
|
|
```kotlin
|
|
val signatureGenerator = KotlinSignatureGenerator()
|
|
val locationService = FoldersLocationService(arguments.outputDir)
|
|
val markdown = JekyllFormatService(locationService, signatureGenerator)
|
|
val generator = FileGenerator(signatureGenerator, locationService, markdown)
|
|
generator.generate(documentation)
|
|
```
|
|
|
|
## Building Dokka
|
|
|
|
Dokka is built with Gradle. To build it, use `./gradlew build`.
|
|
Alternatively, open the project directory in IntelliJ IDEA and use the IDE to build and run Dokka.
|
|
|
|
Here's how to import and configure Dokka in IntelliJ IDEA:
|
|
|
|
* Select "Open" from the IDEA welcome screen, or File > Open if a project is
|
|
already open
|
|
* Select the directory with your clone of Dokka
|
|
* Note: IDEA may have an error after the project is initally opened; it is OK
|
|
to ignore this as the next step will address this error
|
|
* After IDEA opens the project, select File > New > Module from existing sources
|
|
and select the `build.gradle` file from the root directory of your Dokka clone
|
|
* Use the default options and select "OK"
|
|
* After Dokka is loaded into IDEA, open the Gradle tool window (View > Tool
|
|
Windows > Gradle) and click on the top left "Refresh all Gradle projects"
|
|
button
|
|
* Verify the following project settings. In File > Settings > Build, Execution,
|
|
Deployment > Build Tools > Gradle > Runner:
|
|
* Ensure "Delegate IDE build/run actions to gradle" is checked
|
|
* "Gradle Test Runner" should be selected in the "Run tests using" drop-down
|
|
menu
|
|
* Note: After closing and re-opening the project, IDEA may give an error
|
|
message: "Error Loading Project: Cannot load 3 modules". Open up the details
|
|
of the error, and click "Remove Selected", as these module `.iml` files are
|
|
safe to remove.
|