commit | 9c104fa1514ad002d9afb44d96bdcab273361c61 | [log] [tgz] |
---|---|---|
author | Louis Pullen-Freilich <lpf@google.com> | Thu Oct 10 19:49:24 2019 +0100 |
committer | Louis Pullen-Freilich <lpf@google.com> | Wed Nov 20 12:07:09 2019 +0000 |
tree | ed5580e3c914614a6389e310b3432e8f8f1bace6 | |
parent | d408f975820585c73a794f91782bbb950efde456 [diff] |
@sample improvements - Now correctly parses and generates content in between @sample tags - Shows only the related androidx.* imports for each sample, instead of every import in the file Also fixes failing JavaTest Bug: b/139410120 Bug: b/135619809 Change-Id: I05505a2ef432e41d2c91537adc3d1051b3e3530b
Note: This is Google's fork of Dokka, customized for Android API reference docs on 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 in Kotlin files, and can generate documentation in multiple formats including standard Javadoc, HTML and Markdown.
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:
dokka { outputFormat = 'html' outputDirectory = "$buildDir/javadoc" }
The available configuration options are shown below:
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:
./gradlew dokka
More dokka tasks can be added to a project like this:
task dokkaJavadoc(type: org.jetbrains.dokka.gradle.DokkaTask) { outputFormat = 'javadoc' outputDirectory = "$buildDir/javadoc" }
Please see the Dokka Gradle example project for an example.
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
.
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'
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:
<pluginRepositories> <pluginRepository> <id>jcenter</id> <name>JCenter</name> <url>https://jcenter.bintray.com/</url> </pluginRepository> </pluginRepositories>
Minimal Maven configuration is
<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:
<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 for an example.
The Ant task definition is also contained in the dokka-fatjar.jar referenced above. Here's an example of using it:
<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 generatedoutputFormat
- 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 packagesskipDeprecated
- if set, deprecated elements are not included in the generated documentationjdkVersion
- version for linking to JDKimpliedPlatforms
- See platforms section<sourceRoot path="src" platforms="JVM" />
- analogue of src, but allows to specify platforms<packageOptions prefix="kotlin" includeNonPublic="false" reportUndocumented="true" skipDeprecated="false"/>
- Per package options for package kotlin
and sub-packages of itnoStdlibLink
- 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 locationcacheRoot
- 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/dokkaTo run Dokka from the command line, download the Dokka 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:-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/dokkahtml
- minimalistic html format used by defaultjavadoc
- Dokka mimic to javadochtml-as-java
- as html
but using java syntaxmarkdown
- Markdown structured as html
gfm
- GitHub flavored markdownjekyll
- Jekyll compatible markdownkotlin-website*
- internal format used for documentation on kotlinlang.orgDokka can annotate elements with special platform
block with platform requirements
Example of usage can be found on kotlinlang.org
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 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:
Member & Detail has reverse Owner reference, while Link's back reference is also Link.
Nodes that are Details of other nodes cannot have Members.
When we have documentation model, we can render docs in various formats, languages and layouts. We have some core services:
Basically, given the documentation
as a model, we do this:
val signatureGenerator = KotlinSignatureGenerator() val locationService = FoldersLocationService(arguments.outputDir) val markdown = JekyllFormatService(locationService, signatureGenerator) val generator = FileGenerator(signatureGenerator, locationService, markdown) generator.generate(documentation)
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:
build.gradle
file from the root directory of your Dokka clone.iml
files are safe to remove.