diff options
Diffstat (limited to 'docs/src/doc/docs/user_guide/maven/usage.md')
| -rw-r--r-- | docs/src/doc/docs/user_guide/maven/usage.md | 197 |
1 files changed, 197 insertions, 0 deletions
diff --git a/docs/src/doc/docs/user_guide/maven/usage.md b/docs/src/doc/docs/user_guide/maven/usage.md new file mode 100644 index 00000000..a95b6629 --- /dev/null +++ b/docs/src/doc/docs/user_guide/maven/usage.md @@ -0,0 +1,197 @@ +# Using the Maven plugin + +!!! note + Dokka Maven plugin does not support multi-platform projects. + +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 + +## Configuration options + +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> + + <!-- 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 --> + <!-- https://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation --> + <includes> + <include>packages.md</include> + <include>extra.md</include> + </includes> + + <!-- List of sample roots --> + <samples> + <dir>src/test/samples</dir> + </samples> + + <!-- 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 --> + <reportUndocumented>true</reportUndocumented> + <!-- Do not create index pages for empty packages --> + <skipEmptyPackages>true</skipEmptyPackages> + + <!-- 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 --> + <path>${project.basedir}/src/main/kotlin</path> + <!-- 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</url> <!-- //remove src/main/kotlin if you use "./" above --> + <!--Suffix which is used to append the line number to the URL. Use #L for GitHub --> + <lineSuffix>#L</lineSuffix> + </link> + </sourceLinks> + + <!-- Disable linking to online kotlin-stdlib documentation --> + <noStdlibLink>false</noStdlibLink> + + <!-- Disable linking to online JDK documentation --> + <noJdkLink>false</noJdkLink> + + <!-- 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> + + <!-- Allows to use any dokka plugin, eg. GFM format --> + <dokkaPlugins> + <plugin> + <groupId>org.jetbrains.dokka</groupId> + <artifactId>gfm-plugin</artifactId> + <version>${dokka.version}</version> + </plugin> + </dokkaPlugins> + </configuration> +</plugin> +``` + +## Applying plugins +You can add plugins inside the `dokkaPlugins` block: + +```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> + <dokkaPlugins> + <plugin> + <groupId>org.jetbrains.dokka</groupId> + <artifactId>kotlin-as-java-plugin</artifactId> + <version>${dokka.version}</version> + </plugin> + </dokkaPlugins> + </configuration> +</plugin> +``` + +## Example project + +Please see the [Dokka Maven example project](https://github.com/JetBrains/kotlin-examples/tree/master/maven/dokka-maven-example) for an example. |