diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | README.md | 430 | ||||
| -rw-r--r-- | docs/build.gradle.kts | 3 | ||||
| -rw-r--r-- | docs/src/doc/docs/about/FAQ.md | 2 | ||||
| -rw-r--r-- | docs/src/doc/docs/about/slack_channel.md | 4 | ||||
| -rw-r--r-- | docs/src/doc/docs/developer_guide/data_model.md | 103 | ||||
| -rw-r--r-- | docs/src/doc/docs/developer_guide/extension_points.md | 215 | ||||
| -rw-r--r-- | docs/src/doc/docs/developer_guide/introduction.md | 121 | ||||
| -rw-r--r-- | docs/src/doc/docs/dokka_colors.css | 3 | ||||
| -rw-r--r-- | docs/src/doc/docs/expand_navigation.js | 14 | ||||
| -rw-r--r-- | docs/src/doc/docs/favicon.svg | 3 | ||||
| -rw-r--r-- | docs/src/doc/docs/index.md | 16 | ||||
| -rw-r--r-- | docs/src/doc/docs/user_guide/cli/usage.md | 48 | ||||
| -rw-r--r-- | docs/src/doc/docs/user_guide/gradle/usage.md | 300 | ||||
| -rw-r--r-- | docs/src/doc/docs/user_guide/introduction.md | 73 | ||||
| -rw-r--r-- | docs/src/doc/docs/user_guide/maven/usage.md | 197 | ||||
| -rw-r--r-- | docs/src/doc/mkdocs.yml | 64 | ||||
| -rw-r--r-- | settings.gradle.kts | 2 |
18 files changed, 1172 insertions, 427 deletions
@@ -1,7 +1,6 @@ *.ipr *.iml -doc ### Maven template target/ pom.xml.tag @@ -7,48 +7,7 @@ and can generate documentation in multiple formats including standard Javadoc, H ## Using dokka -### Plugins -Dokka can be customized with plugins. Each output format is internally a plugin. -Additionally, `kotlin-as-java` plugin can be used to generate documentation as seen from Java perspective. -Currently maintained plugins are: -* `dokka-base` - the main plugin needed to run dokka, contains html format -* `gfm-plugin` - configures `GFM` output format -* `jekyll-plugin` - configures `Jekyll` output format -* `javadoc-plugin` - configures `Javadoc` output format, automatically applies `kotlin-as-java-plugin` -* `kotlin-as-java-plugin` - translates Kotlin definitions to Java - -Please see the usage instructions below for how to add plugins to dokka. - -### Source sets -Dokka generates documentation based on source sets. - -For single-platform & multi-platform projects, source sets are the same as in Kotlin plugin: - - * One source set for each platform, eg. `jvmMain` or `jsMain`; - * One source set for each common source set, eg. the default `commonMain` and custom ones like `jsAndJvmMain`. - -When configuring multi-platform projects manually (eg. in the CLI or in Gradle without the Kotlin Gradle Plugin) -source sets must declare their dependent source sets. -Eg. in the following Kotlin plugin configuration: - -* `jsMain` and `jvmMain` both depend on `commonMain` (by default and transitively) and `jsAndJvmMain`; -* `linuxX64Main` only depends on `commonMain`. - -```kotlin -kotlin { // Kotlin plugin configuration - jvm() - js() - linuxX64() - - sourceSets { - val commonMain by getting {} - val jvmAndJsSecondCommonMain by creating { dependsOn(commonMain) } - val jvmMain by getting { dependsOn(jvmAndJsSecondCommonMain) } - val jsMain by getting { dependsOn(jvmAndJsSecondCommonMain) } - val linuxX64Main by getting { dependsOn(commonMain) } - } -} -``` +**Full documentation is available at [http://kotlin.github.io/dokka](http://kotlin.github.io/dokka)** ### Using the Gradle plugin _Note: If you are upgrading from 0.10.x to a current release of dokka, please have a look at our @@ -78,194 +37,8 @@ pluginManagement { } ``` -You can also use the legacy plugin application method with `buildscript` block. -Note that by using the `buildscript` way type-safe accessors are not available in Gradle Kotlin DSL, -eg. you'll have to use `named<DokkaTask>("dokkaHtml")` instead of `dokkaHtml`: - -```kotlin -buildscript { - repositories { - jcenter() - } - dependencies { - classpath("org.jetbrains.dokka:dokka-gradle-plugin:${dokka_version}") - } -} -repositories { - jcenter() // or maven(url="https://dl.bintray.com/kotlin/dokka") -} - -apply(plugin="org.jetbrains.dokka") -``` - The plugin adds `dokkaHtml`, `dokkaJavadoc`, `dokkaGfm` and `dokkaJekyll` tasks to the project. -Each task corresponds to one output format, so you should run `dokkaGfm` when you want to have a documentation in `GFM` format. -Output formats are explained [there](#output_formats) - -If you encounter any problems when migrating from older versions of dokka, please see the [FAQ](https://github.com/Kotlin/dokka/wiki/faq). - -Minimal dokka configuration (with only custom output directory) - -Kotlin -```kotlin -tasks.dokkaHtml.configure { - outputDirectory.set(buildDir.resolve("dokka")) -} -``` - - -Groovy -```kotlin -tasks.named("dokkaHtml") { - outputDirectory.set(buildDir.resolve("dokka")) -} -``` - - -Dokka documents single-platform as well as multi-platform projects. -Most of the configuration options are set per one source set. -The available configuration options for are shown below: - -```kotlin -dokkaHtml { - outputDirectory.set(buildDir.resolve("dokka")) - - // Used for disabling auto extraction of sources and platforms - // When set to true kotlinTasks are also omitted - disableAutoconfiguration.set(false) - - // Use default or set to custom path to cache directory - // to enable package-list caching - // When this is set to default, caches are stored in $USER_HOME/.cache/dokka - cacheRoot.set(file("default")) - dokkaSourceSets { - configureEach { // Or source set name, for single-platform the default source sets are `main` and `test` - - // Used when configuring source sets manually for declaring which source sets this one depends on - dependsOn("otherSourceSetName") - - // Use to include or exclude non public members - includeNonPublic.set(false) - - // Do not output deprecated members. Applies globally, can be overridden by packageOptions - skipDeprecated.set(false) - - // Emit warnings about not documented members. Applies globally, also can be overridden by packageOptions - reportUndocumented.set(true) - - // Do not create index pages for empty packages - skipEmptyPackages.set(true) - - // This name will be shown in the final output - displayName.set("JVM") - - // Platform used for code analysis. See the "Platforms" section of this readme - platform.set(org.jetbrains.dokka.Platform.jvm) - - // Property used for manual addition of files to the classpath - // This property does not override the classpath collected automatically but appends to it - classpath.from(file("libs/dependency.jar")) - - // List of files with module and package documentation - // https://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation - includes.from("packages.md", "extra.md") - - // List of files or directories containing sample code (referenced with @sample tags) - samples.from("samples/basic.kt", "samples/advanced.kt") - - // By default, sourceRoots are taken from Kotlin Plugin and kotlinTasks, following roots will be appended to them - // Repeat for multiple sourceRoots - sourceRoot.from(file("src")) - - // Specifies the location of the project source code on the Web. - // If provided, Dokka generates "source" links for each declaration. - // Repeat for multiple mappings - sourceLink { - // Unix based directory relative path to the root of the project (where you execute gradle respectively). - localDirectory.set(file("src/main/kotlin")) - - // URL showing where the source code can be accessed through the web browser - remoteUrl.set(java.net.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 - remoteLineSuffix.set("#L") - } - - // Used for linking to JDK documentation - jdkVersion.set(8) - - // Disable linking to online kotlin-stdlib documentation - noStdlibLink.set(false) - - // Disable linking to online JDK documentation - noJdkLink.set(false) - - // Disable linking to online Android documentation (only applicable for Android projects) - noAndroidSdkLink.set(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 = URL("https://example.com/docs/") - - // If package-list file is located in non-standard location - // packageListUrl = URL("file:///home/user/localdocs/package-list") - } - - // Allows to customize documentation generation options on a per-package basis - // Repeat for multiple packageOptions - perPackageOption { - prefix.set("kotlin") // will match kotlin and all sub-packages of it - // All options are optional, default values are below: - skipDeprecated.set(false) - reportUndocumented.set(true) // Emit warnings about not documented members - includeNonPublic.set(false) - } - // Suppress a package - perPackageOption { - prefix.set("kotlin.internal") // will match kotlin.internal and all sub-packages of it - suppress.set(true) - } - } - } -``` - -#### Multiplatform -Dokka supports single-platform and multi-platform projects using source sets abstraction. For most mutli-platform projects -you should assume that dokka's source sets correspond to Kotlin plugin's source sets. Main source sets will be registered -and configured automatically - -Kotlin -```kotlin -kotlin { // Kotlin Multiplatform plugin configuration - jvm() - js("customName") -} - -tasks.withType<DokkaTask>().configureEach { - // custom output directory - outputDirectory.set(buildDir.resolve("dokka")) - - dokkaSourceSets { - named("customNameMain") { // The same name as in Kotlin Multiplatform plugin, so the sources are fetched automatically - includes.from("packages.md", "extra.md") - samples.from("samples/basic.kt", "samples/advanced.kt") - } - - register("differentName") { // Different name, so source roots must be passed explicitly - displayName = "JVM" - platform = "jvm" - sourceRoots.from(kotlin.sourceSets.getByName("jvmMain").kotlin.srcDirs) - sourceRoots.from(kotlin.sourceSets.getByName("commonMain").kotlin.srcDirs) - } - } - } -``` - -If you want to share the configuration between source sets, you can use Gradle's `configureEach` - #### Applying plugins Dokka plugin creates Gradle configuration for each output format in the form of `dokka${format}Plugin`: @@ -295,9 +68,6 @@ To generate the documentation, use the appropriate `dokka${format}` Gradle task: Please see the [Dokka Gradle example project](https://github.com/Kotlin/kotlin-examples/tree/master/gradle/dokka/dokka-gradle-example) for an example. -#### FAQ -If you encounter any problems, please see the [FAQ](https://github.com/Kotlin/dokka/wiki/faq). - #### Android Make sure you apply dokka after `com.android.library` and `kotlin-android`. @@ -359,25 +129,7 @@ The Maven plugin is available in JCenter. You need to add the JCenter repository </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`. +Documentation is by default generated in `target/dokka`. The following goals are provided by the plugin: @@ -385,127 +137,6 @@ The following goals are provided by the plugin: * `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> - - <!-- 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: @@ -543,36 +174,6 @@ To generate documentation, run the following command: ``` java -jar dokka-cli.jar <arguments> ``` -Dokka supports the following command line arguments: - - * `-outputDir` - the output directory where the documentation is generated - * `-cacheRoot` - cache directory to enable package-list caching - * `-pluginsClasspath` - artifacts with dokka plugins, separated by `;`. At least dokka base and all its dependencies must be added there - * `-offlineMode` - do not resolve package-lists online - * `-failOnWarning` - throw an exception instead of a warning - * `-globalPackageOptions` - per package options added to all source sets - * `-globalLinks` - external documentation links added to all source sets - * `-globalSrcLink` - source links added to all source sets - * `-sourceSet` - (repeatable) - configuration for a single source set. Following this argument, you can pass other arguments: - * `-moduleName` - (required) - module name used as a part of source set ID when declaring dependent source sets - * `-sourceSetName` - source set name as a part of source set ID when declaring dependent source sets - * `-displayName` - source set name displayed in the generated documentation - * `-src` - list of source files or directories separated by `;` - * `-classpath` - list of directories or .jar files to include in the classpath (used for resolving references) separated by `;` - * `-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) separated by `;` - * `-includes` - list of files containing the documentation for the module and individual packages separated by `;` - * `-includeNonPublic` - include protected and private code - * `-skipDeprecated` - if set, deprecated elements are not included in the generated documentation - * `-reportUndocumented` - warn about undocumented members - * `-skipEmptyPackages` - do not create index pages for empty packages - * `-packageOptions` - list of package options in format `prefix,-deprecated,-privateApi,+reportUndocumented;prefix, ...`, separated by `;` - * `-links` - list of external documentation links in format `url^packageListUrl^^url2...`, separated by `;` - * `-srcLink` - mapping between a source directory and a Web site for browsing the code in format `<path>=<url>[#lineSuffix]` - * `-noStdlibLink` - disable linking to online kotlin-stdlib documentation - * `-noJdkLink` - disable linking to online JDK documentation - * `-jdkVersion` - version of JDK to use for linking to JDK JavaDoc - * `-analysisPlatform` - platform used for analysis, see the [Platforms](#platforms) section - * `-dependentSourceSets` - list of dependent source sets in format `moduleName/sourceSetName`, separated by `;` You can also use a JSON file with dokka configuration: ``` @@ -597,28 +198,5 @@ dependencies{ } ``` -### Platforms<a name="platforms"></a> - -Each dokka source set is analyzed for a specific platform. The platform should be extracted automatically from the Kotlin plugin. -In case of a manual source set configuration, you have to select one of the following: - * `jvm` - * `js` - * `native` - * `common` - -## 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 2019.3: - * 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 -* 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 +#### FAQ +If you encounter any problems, please see the [FAQ](https://github.com/Kotlin/dokka/wiki/faq). diff --git a/docs/build.gradle.kts b/docs/build.gradle.kts new file mode 100644 index 00000000..914f2b8d --- /dev/null +++ b/docs/build.gradle.kts @@ -0,0 +1,3 @@ +plugins { + id("ru.vyarus.mkdocs") version "2.0.1" +} diff --git a/docs/src/doc/docs/about/FAQ.md b/docs/src/doc/docs/about/FAQ.md new file mode 100644 index 00000000..ba4a7acf --- /dev/null +++ b/docs/src/doc/docs/about/FAQ.md @@ -0,0 +1,2 @@ +# FAQ +If you encounter any problems, please see the [FAQ](https://github.com/Kotlin/dokka/wiki/faq). diff --git a/docs/src/doc/docs/about/slack_channel.md b/docs/src/doc/docs/about/slack_channel.md new file mode 100644 index 00000000..6879dc7d --- /dev/null +++ b/docs/src/doc/docs/about/slack_channel.md @@ -0,0 +1,4 @@ +# Slack channel + +For more information or help, feel free to ask questions in the [official Kotlin Slack Channel](https://kotlinlang.slack.com) + diff --git a/docs/src/doc/docs/developer_guide/data_model.md b/docs/src/doc/docs/developer_guide/data_model.md new file mode 100644 index 00000000..45200004 --- /dev/null +++ b/docs/src/doc/docs/developer_guide/data_model.md @@ -0,0 +1,103 @@ +# Dokka Data Model + +There a four data models that dokka uses: Documentable Model, Documentation Model, Page Model and Content Model. + +## Documentable Model + +Documentable model represents parsed data, returned by compiler analysis. It retains basic order structure of parsed `Psi` or `Descriptor` models. + +After creation, it is a collection of trees, each with `DModel` as a root. After the Merge step, all trees are folded into one. + +The main building block of this model is `Documentable` class, that is a base class for all more specific types that represents elements of parsed Kotlin and Java classes with pretty self-explanatory names: `DPackage`, `DFunction` and so on. `DClasslike` is a base for class-like elements, such as Classes, Enums, Interfaces and so on. + +There are three non-documentable classes important for the model: `DRI`, `SourceSetDependent` and `ExtraProperty`. + +* `DRI` (Dokka Resource Identifier) is an unique value that identifies specific `Documentable`. All references to other documentables different than direct ownership are described using DRIs. For example, `DFunction` with parameter of type `X` has only X's DRI, not the actual reference to X's Documentable object. +* `SourceSetDependent` is a map that handles multiplatform data, by connecting platform-specific data, declared with either `expect` or `actual` modifier, to a particular Source Set +* `ExtraProperty` is used to store any additional information that falls outside of regular model. It is highly recommended to use extras to provide any additional information when creating custom Dokka plugins. This element is a bit more complex, so you can read more about how to use it below. + +### `ExtraProperty` class usage + +`ExtraProperty` classes are used both by Documentable and Content models. To declare a new extra, you need to implement `ExtraProperty` interface. + +```kotlin +interface ExtraProperty<in C : Any> { + interface Key<in C : Any, T : Any> { + fun mergeStrategyFor(left: T, right: T): MergeStrategy<C> = MergeStrategy.Fail { + throw NotImplementedError("Property merging for $this is not implemented") + } + } + + val key: Key<C, *> +} +``` + +It is advised to use following pattern when declaring new extras: + +```kotlin +data class CustomExtra( [any values relevant to your extra ] ): ExtraProperty<Documentable> { + companion object : CustomExtra.Key<Documentable, CustomExtra> + override val key: CustomExtra.Key<Documentable, *> = CustomExtra +} +``` +Merge strategy for extras is invoked only if merged objects have different values for same Extra. If you don't expect it to happen, you can omit implementing `mergeStrategyFor` function. + +All extras for `ContentNode` and `Documentable` classes are stored in `PropertyContainer<C : Any>` class instances. The `C` generic class parameter limits the type of properties, that can be stored in the container - it must match generic `C` class parameter from `ExtraProperty` interface. For example, if you would create `DFunction`-only `ExtraProperty`, it will be limited to be added only to `PropertyContainer<DFunction>`. + +In following example we will create `Documentable`-only property, store it in the container and then retrieve its value: + +```kotlin +data class CustomExtra(val customExtraValue: String) : ExtraProperty<Documentable> { + + companion object: ExtraProperty.Key<Documentable, CustomExtra> + + override val key: ExtraProperty.Key<Documentable, *> = CustomExtra +} + +val extra : PropertyContainer<DFunction> = PropertyContainer.withAll( + CustomExtra("our value") +) + +val customExtraValue : String? = extra[CustomProperty]?.customExtraValue +``` + +You can also use extras as markers, without storing any data in them: + +```kotlin + +object MarkerExtra : ExtraProperty<Any>, ExtraProperty.Key<Any, MarkerExtra> { + override val key: ExtraProperty.Key<Any, *> = this +} + +val extra : PropertyContainer<Any> = PropertyContainer.withAll(MarkerExtra) + +val isMarked : Boolean = extra[MarkerExtra] != null + +``` + +## Documentation Model + +Documentation model is used along Documentable Model to store data obtained by parsing code commentaries. + +There are three important classes here: + +* `DocTag` describes a specific documentation syntax element, for example: header, footer, list, link, raw text, paragraph, etc. +* `TagWrapper` described a whole comment description or a specific comment tag, for example: @See, @Returns, @Author; and holds consisting `DocTag` elements +* `DocumentationNode` acts as a container for `TagWrappers` for a specific `Documentable` + +DocumentationNodes are references by a specific `Documentable` + +## Page Model + +Page Model represents the structure of future generated documentation pages and is independent of the final output format, which each node corresponding to exactly one output file. `Renderer` is processing each page separately.Subclasses of `PageNode` represents different kinds of rendered pages for Modules, Packages, Classes etc. + +The Page Model is a tree structure, with `RootPageNode` being the root. + +## Content Model + +Content Model describes how the actual page content is presented. It organizes it's structure into groups, tables, links, etc. Each node is identified by unique `DCI` (Dokka Content Identifier) and all references to other nodes different than direct ownership are described using DCIs. + +`DCI` aggregates `DRI`s of all `Documentables` that make up specific `ContentNode`. + +Also, all `ExtraProperty` info from consisting `Documentable`s is propagated into Content Model and available for `Renderer`. + diff --git a/docs/src/doc/docs/developer_guide/extension_points.md b/docs/src/doc/docs/developer_guide/extension_points.md new file mode 100644 index 00000000..ca552c3b --- /dev/null +++ b/docs/src/doc/docs/developer_guide/extension_points.md @@ -0,0 +1,215 @@ +# Extension points + +## Core extension points + +We will discuss all base extension points along with the steps, that `DokkaGenerator` does to build a documentation. + +### Setting up Kotlin and Java analysis process and initializing plugins + +The provided Maven / CLI / Gradle configuration is read.Then, all the `DokkaPlugin` classes are loaded and the extensions are created. + + No entry points here. + +### Creating documentation models + +The documentation models are created. + +This step uses `DokkaCore.sourceToDocumentableTranslator` entry point. All extensions registered using this entry point will be invoked. Each of them is required to implement `SourceToDocumentableTranslator` interface: + +```kotlin +interface SourceToDocumentableTranslator { + fun invoke(sourceSet: SourceSetData, context: DokkaContext): DModule +} +``` +By default, two translators are created: + +* `DefaultDescriptorToDocumentableTranslator` that handles Kotlin files +* `DefaultPsiToDocumentableTranslator` that handles Java files + +After this step, all data from different source sets and languages are kept separately. + +### Pre-merge documentation transform + +Here you can apply any transformation to model data before different source sets are merged. + +This step uses `DokkaCore.preMergeDocumentableTransformer` entry point. All extensions registered using this entry point will be invoked. Each of them is required to implement `PreMergeDocumentableTransformer` interface: + +```kotlin +interface PreMergeDocumentableTransformer { + operator fun invoke(modules: List<DModule>, context: DokkaContext): List<DModule> +} +``` +By default, three transformers are created: + +* `DocumentableVisibilityFilter` that, depending on configuration, filters out all private members from declared packages +* `ActualTypealiasAdder` that handles Kotlin typealiases +* `ModuleAndPackageDocumentationTransformer` that creates documentation content for models and packages itself + +### Merging + +All `DModule` instances are merged into one. + +This step uses `DokkaCore.documentableMerger` entry point. It is required to have exactly one extension registered for this entry point. Having more will trigger an error, unless only one is not overridden. + +The extension is required to implement `DocumentableMerger` interface: + +```kotlin +interface DocumentableMerger { + operator fun invoke(modules: Collection<DModule>, context: DokkaContext): DModule +} +``` + +By default, `DefaultDocumentableMerger` is created. This extension is treated as a fallback, so it can be overridden by a custom one. + +### Merged data transformation + +You can apply any transformation to already merged data + +This step uses `DokkaCore.documentableTransformer` entry point. All extensions registered using this entry point will be invoked. Each of them is required to implement `DocumentableTransformer` interface: + +```kotlin +interface DocumentableTransformer { + operator fun invoke(original: DModule, context: DokkaContext): DModule +} +``` + +By default, `InheritorsExtractorTransformer` is created, that extracts inherited classes data across source sets and creates inheritance map. + +### Creating page models + +The documentable model is translated into page format, that aggregates all tha data that will be available for different pages of documentation. + +This step uses `DokkaCore.documentableToPageTranslator` entry point. It is required to have exactly one extension registered for this entry point. Having more will trigger an error, unless only one is not overridden. + +The extension is required to implement `DocumentableToPageTranslator` interface: + +```kotlin +interface DocumentableToPageTranslator { + operator fun invoke(module: DModule): ModulePageNode +} +``` + +By default, `DefaultDocumentableToPageTranslator` is created. This extension is treated as a fallback, so it can be overridden by a custom one. + +### Transforming page models + +You can apply any transformations to paged data. + +This step uses `DokkaCore.pageTransformer` entry point. All extensions registered using this entry point will be invoked. Each of them is required to implement `PageTransformer` interface: + +```kotlin +interface PageTransformer { + operator fun invoke(input: RootPageNode): RootPageNode +} +``` +By default, two transformers are created: + +* `PageMerger` merges some pages depending on `MergeStrategy` +* `DeprecatedStrikethroughTransformer` marks all deprecated members on every page + +### Rendering + +All pages are rendered to desired format. + +This step uses `DokkaCore.renderer` entry point. It is required to have exactly one extension registered for this entry point. Having more will trigger an error, unless only one is not overridden. + +The extension is required to implement `Renderer` interface: + +```kotlin +interface Renderer { + fun render(root: RootPageNode) +} +``` + +By default, only `HtmlRenderer`, that extends basic `DefaultRenderer`, is created, but it will be registered only if configuration parameter `format` is set to `html`. Using any other value without providing valid renderer will cause dokka to fail. + +## Multimodule page generation endpoints + +Multimodule page generation is a separate process, that declares two additional entry points: + +### Multimodule page creation + +Generation of the page that points to all module for which we generates documentation. + +This step uses `CoreExtensions.allModulePageCreator` entry point. It is required to have exactly one extension registered for this entry point. Having more will trigger an error, unless only one is not overridden. + +The extension is required to implement `PageCreator` interface: + +```kotlin +interface PageCreator { + operator fun invoke(): RootPageNode +} +``` + +By default, `MultimodulePageCreator` is created. This extension is treated as a fallback, so it can be replaced by a custom one. + +### Multimodule page transformation + +Additional transformation that we might apply for multimodule page. + +This step uses `CoreExtensions.allModulePageTransformer` entry point. All extensions registered using this entry point will be invoked. Each of them is required to implement common `PageTransformer` interface. + +## Default extensions' extension points + +Default core extension points already have an implementation for providing basic dokka functionality. All of them are declared in `DokkaBase` plugin. If you don't want this default extensions to load, all you need to do is not load dokka base and load your plugin instead. + + ```kotlin +val customPlugin by configurations.creating + +dependencies { + customPlugin("[custom plugin load signature]") +} +tasks { + val dokka by getting(DokkaTask::class) { + pluginsConfig = alternativeAndIndependentPlugins + outputDirectory = dokkaOutputDir + outputFormat = "html" + [...] + } +} +``` + + You will then need to implement extensions for all core extension points. + +`DokkaBase` also register several new extension points, with which you can change default behaviour of `DokkaBase` extensions. In order to use them, you need to add `dokka-base` to you dependencies: + +```kotlin + compileOnly("org.jetbrains.dokka:dokka-base:<dokka_version>") +``` + +Then, you need to obtain `DokkaBase` instance using `plugin` function: + +```kotlin +class SamplePlugin : DokkaPlugin() { + + val dokkaBase = plugin<DokkaBase>() + + val extension by extending { + dokkaBase.pageMergerStrategy with SamplePageMergerStrategy order { + before(dokkaBase.fallbackMerger) + } + } +} + +object SamplePageMergerStrategy: PageMergerStrategy { + override fun tryMerge(pages: List<PageNode>, path: List<String>): List<PageNode> { + ... + } + +} +``` + +### Following extension points are available with base plugin + +| Entry point | Function | Required interface | Used by | Singular | Preregistered extensions +|---|:---|:---:|:---:|:---:|:---:| +| `pageMergerStrategy` | determines what kind of pages should be merged | `PageMergerStrategy` | `PageMerger` | false | `FallbackPageMergerStrategy` `SameMethodNamePageMergerStrategy` | +| `commentsToContentConverter` | transforms comment model into page content model | `CommentsToContentConverter` | `DefaultDocumentableToPageTransformer` `SignatureProvider` | true | `DocTagToContentConverter` | +| `signatureProvider` | provides representation of methods signatures | `SignatureProvider` | `DefaultDocumentableToPageTransformer` | true | `KotlinSignatureProvider` | +| `locationProviderFactory` | provides `LocationProvider` instance that returns paths for requested elements | `LocationProviderFactory` | `DefaultRenderer` `HtmlRenderer` `PackageListService` | true | `DefaultLocationProviderFactory` which returns `DefaultLocationProvider` | +| `externalLocationProviderFactory` | provides `ExternalLocationProvider` instance that returns paths for elements that are not part of generated documentation | `ExternalLocationProviderFactory` | `DefaultLocationProvider` | false | `JavadocExternalLocationProviderFactory` `DokkaExternalLocationProviderFactory` | +| `outputWriter` | writes rendered pages files | `OutputWriter` | `DefaultRenderer` `HtmlRenderer` | true | `FileWriter`| +| `htmlPreprocessors` | transforms page content before HTML rendering | `PageTransformer`| `DefaultRenderer` `HtmlRenderer` | false | `RootCreator` `SourceLinksTransformer` `NavigationPageInstaller` `SearchPageInstaller` `ResourceInstaller` `StyleAndScriptsAppender` `PackageListCreator` | +| `samplesTransformer` | transforms content for code samples for HTML rendering | `SamplesTransformer` | `HtmlRenderer` | true | `DefaultSamplesTransformer` | + + diff --git a/docs/src/doc/docs/developer_guide/introduction.md b/docs/src/doc/docs/developer_guide/introduction.md new file mode 100644 index 00000000..c69d71e1 --- /dev/null +++ b/docs/src/doc/docs/developer_guide/introduction.md @@ -0,0 +1,121 @@ +# Guide to Dokka Plugin development + +## 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 2019.3: + +* 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.kts` file from the root directory of your Dokka clone +* 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 + + +## Configuration + +Dokka requires configured `Kotlin plugin` and `dokka-core` dependency. + +```kotlin +plugins { + kotlin("jvm") version "<kotlin_version>" +} + +dependencies { + compileOnly("org.jetbrains.dokka:dokka-core:<dokka_version>") +} + +tasks.withType<KotlinCompile> { + kotlinOptions.jvmTarget = "1.8" +} +``` + +## Building sample plugin + +In order to load a plugin into dokka, your class must extend `DokkaPlugin` class. All instances are automatically loaded during dokka setup using `java.util.ServiceLoader`. + +Dokka provides a set of entry points, for which user can create their own implementations. They must be delegated using `DokkaPlugin.extending(definition: ExtendingDSL.() -> Extension<T, *, *>)` function,that returns a delegate `ExtensionProvider` with supplied definition. + +To create a definition, you can use one of two infix functions`with(T)` or `providing( (DokkaContext) -> T)` where `T` is the type of an extended endpoint. You can also use infix functions: + +* `applyIf( () -> Boolean )` to add additional condition specifying whether or not the extension should be used +* `order((OrderDsl.() -> Unit))` to determine if your extension should be used before or after another particular extension for the same endpoint +* `override( Extension<T, *, *> )` to override other extension. Overridden extension won't be loaded and overridding one will inherit ordering from it. + +Following sample provides custom translator object as a `DokkaCore.sourceToDocumentableTranslator` + +```kotlin +package org.jetbrains.dokka.sample + +import org.jetbrains.dokka.plugability.DokkaPlugin + +class SamplePlugin : DokkaPlugin() { + extension by extending { + DokkaCore.sourceToDocumentableTranslator with CustomSourceToDocumentableTranslator + } +} + +object CustomSourceToDocumentableTranslator: SourceToDocumentableTranslator { + override fun invoke(sourceSet: SourceSetData, context: DokkaContext): DModule +} +``` + +### Registering extension point + +You can register your own extension point using `extensionPoint` function declared in `DokkaPlugin` class + +```kotlin +class SamplePlugin : DokkaPlugin() { + val extensionPoint by extensionPoint<SampleExtensionPointInterface>() +} + +interface SampleExtensionPointInterface +``` + +### Obtaining extension instance + +All registered plugins are accessible with `DokkaContext.plugin` function. All plugins that extends `DokkaPlugin` can use `DokkaPlugin.plugin` function, that uses underlying `DokkaContext` instance. If you want to pass context to your extension, you can obtain it using aforementioned `providing` infix function. + +With plugin instance obtained, you can browse extensions registered for this plugins' extension points using `querySingle` and `query` methods: + +```kotlin + context.plugin<DokkaBase>().query { htmlPreprocessors } + context.plugin<DokkaBase>().querySingle { samplesTransformer } +``` + +You can also browse `DokkaContext` directly, using `single` and `get` methods: + +```kotlin +class SamplePlugin : DokkaPlugin() { + + val extensionPoint by extensionPoint<SampleExtensionPointInterface>() + val anotherExtensionPoint by extensionPoint<AnotherSampleExtensionPointInterface>() + + val extension by extending { + extensionPoint with SampleExtension() + } + + val anotherExtension by extending { + anotherExtensionPoint providing { context -> + AnotherSampleExtension(context.single(extensionPoint)) + } + } +} + +interface SampleExtensionPointInterface +interface AnotherSampleExtensionPointInterface + +class SampleExtension: SampleExtensionPointInterface +class AnotherSampleExtension(sampleExtension: SampleExtensionPointInterface): AnotherSampleExtensionPointInterface +``` + diff --git a/docs/src/doc/docs/dokka_colors.css b/docs/src/doc/docs/dokka_colors.css new file mode 100644 index 00000000..9e45c919 --- /dev/null +++ b/docs/src/doc/docs/dokka_colors.css @@ -0,0 +1,3 @@ +.md-header { + background-color: #F8873C; +} diff --git a/docs/src/doc/docs/expand_navigation.js b/docs/src/doc/docs/expand_navigation.js new file mode 100644 index 00000000..cef32f2c --- /dev/null +++ b/docs/src/doc/docs/expand_navigation.js @@ -0,0 +1,14 @@ +document.addEventListener("DOMContentLoaded", function() { + let nav = document.getElementsByClassName("md-nav"); + for(let i = 0; i < nav.length; i++) { + if (nav.item(i).getAttribute("data-md-level")) { + nav.item(i).style.display = 'block'; + nav.item(i).style.overflow = 'visible'; + } + } + + nav = document.getElementsByClassName("md-nav__toggle"); + for(let i = 0; i < nav.length; i++) { + nav.item(i).checked = true; + } +}); diff --git a/docs/src/doc/docs/favicon.svg b/docs/src/doc/docs/favicon.svg new file mode 100644 index 00000000..1b3b3670 --- /dev/null +++ b/docs/src/doc/docs/favicon.svg @@ -0,0 +1,3 @@ +<svg width="26" height="26" viewBox="0 0 26 26" fill="none" xmlns="http://www.w3.org/2000/svg"> +<path d="M26 26H0V0H26L12.9243 12.9747L26 26Z" fill="#F8873C"/> +</svg> diff --git a/docs/src/doc/docs/index.md b/docs/src/doc/docs/index.md new file mode 100644 index 00000000..9472d738 --- /dev/null +++ b/docs/src/doc/docs/index.md @@ -0,0 +1,16 @@ +# dokka [](https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub) [/statusIcon)](https://teamcity.jetbrains.com/viewType.html?buildTypeId=Kotlin_Dokka_DokkaAntMavenGradle&branch_KotlinTools_Dokka=%3Cdefault%3E&tab=buildTypeStatusDiv) + +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. + +## Integrations +Dokka provides support for the following build systems: + +* [Gradle](user_guide/gradle/usage.md) +* [Maven](user_guide/maven/usage.md) +* [Command line](user_guide/cli/usage.md) + +!!! note + The Gradle plugin is the preferred way to use dokka diff --git a/docs/src/doc/docs/user_guide/cli/usage.md b/docs/src/doc/docs/user_guide/cli/usage.md new file mode 100644 index 00000000..9fdc6a24 --- /dev/null +++ b/docs/src/doc/docs/user_guide/cli/usage.md @@ -0,0 +1,48 @@ +# Using command line + +To run Dokka from the command line, download the [Dokka CLI runner](https://github.com/Kotlin/dokka/releases/download/v1.4.0-rc/dokka-cli-1.4.0-rc.jar). +To generate documentation, run the following command: +``` +java -jar dokka-cli.jar <arguments> +``` + +## Configuration options + +Dokka supports the following command line arguments: + + * `-outputDir` - the output directory where the documentation is generated + * `-moduleName` - (required) - module name used as a part of source set ID when declaring dependent source sets + * `-cacheRoot` - cache directory to enable package-list caching + * `-pluginsClasspath` - artifacts with dokka plugins, separated by `;`. At least dokka base and all its dependencies must be added there + * `-offlineMode` - do not resolve package-lists online + * `-failOnWarning` - throw an exception instead of a warning + * `-globalPackageOptions` - per package options added to all source sets + * `-globalLinks` - external documentation links added to all source sets + * `-globalSrcLink` - source links added to all source sets + * `-sourceSet` - (repeatable) - configuration for a single source set. Following this argument, you can pass other arguments: + * `-sourceSetName` - source set name as a part of source set ID when declaring dependent source sets + * `-displayName` - source set name displayed in the generated documentation + * `-src` - list of source files or directories separated by `;` + * `-classpath` - list of directories or .jar files to include in the classpath (used for resolving references) separated by `;` + * `-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) separated by `;` + * `-includes` - list of files containing the documentation for the module and individual packages separated by `;` + * `-includeNonPublic` - include protected and private code + * `-skipDeprecated` - if set, deprecated elements are not included in the generated documentation + * `-reportUndocumented` - warn about undocumented members + * `-skipEmptyPackages` - do not create index pages for empty packages + * `-packageOptions` - list of package options in format `prefix,-deprecated,-privateApi,+reportUndocumented;prefix, ...`, separated by `;` + * `-links` - list of external documentation links in format `url^packageListUrl^^url2...`, separated by `;` + * `-srcLink` - mapping between a source directory and a Web site for browsing the code in format `<path>=<url>[#lineSuffix]` + * `-noStdlibLink` - disable linking to online kotlin-stdlib documentation + * `-noJdkLink` - disable linking to online JDK documentation + * `-jdkVersion` - version of JDK to use for linking to JDK JavaDoc + * `-analysisPlatform` - platform used for analysis, see the [Platforms](#platforms) section + * `-dependentSourceSets` - list of dependent source sets in format `moduleName/sourceSetName`, separated by `;` + +You can also use a JSON file with dokka configuration: + ``` + java -jar <dokka_cli.jar> <path_to_config.json> + ``` + +## Applying plugins +To apply a dokka plugin you have to provide it and all its dependencies in the `pluginsClasspath` parameter diff --git a/docs/src/doc/docs/user_guide/gradle/usage.md b/docs/src/doc/docs/user_guide/gradle/usage.md new file mode 100644 index 00000000..06af7174 --- /dev/null +++ b/docs/src/doc/docs/user_guide/gradle/usage.md @@ -0,0 +1,300 @@ +# Using the Gradle plugin + +!!! important + If you are upgrading from 0.10.x to a current release of dokka, please have a look at our + [migration guide](https://github.com/Kotlin/dokka/blob/master/runners/gradle-plugin/MIGRATION.md) + +The preferred way is to use `plugins` block. Since dokka is currently not published to the Gradle plugin portal, +you not only need to add `dokka` to the `build.gradle.kts` file, but you also need to modify the `settings.gradle.kts` file: + +build.gradle.kts: +```kotlin +plugins { + id("org.jetbrains.dokka") version "1.4.0-rc" +} + +repositories { + jcenter() // or maven(url="https://dl.bintray.com/kotlin/dokka") +} +``` + +settings.gradle.kts: +```kotlin +pluginManagement { + repositories { + gradlePluginPortal() + jcenter() + } +} +``` + +You can also use the legacy plugin application method with `buildscript` block. +Note that by using the `buildscript` way type-safe accessors are not available in Gradle Kotlin DSL, +eg. you'll have to use `named<DokkaTask>("dokkaHtml")` instead of `dokkaHtml`: + +```kotlin +buildscript { + repositories { + jcenter() + } + dependencies { + classpath("org.jetbrains.dokka:dokka-gradle-plugin:${dokka_version}") + } +} +repositories { + jcenter() // or maven(url="https://dl.bintray.com/kotlin/dokka") +} + +apply(plugin="org.jetbrains.dokka") +``` + +The plugin adds `dokkaHtml`, `dokkaJavadoc`, `dokkaGfm` and `dokkaJekyll` tasks to the project. + +Each task corresponds to one output format, so you should run `dokkaGfm` when you want to have a documentation in `GFM` format. +Output formats are explained in [the introduction](../introduction.md#output-formats) + +If you encounter any problems when migrating from older versions of dokka, please see the [FAQ](https://github.com/Kotlin/dokka/wiki/faq). + +Minimal dokka configuration (with only custom output directory) + +Kotlin +```kotlin +tasks.dokkaHtml.configure { + outputDirectory.set(buildDir.resolve("dokka")) +} +``` + + +Groovy +```kotlin +tasks.named("dokkaHtml") { + outputDirectory.set(buildDir.resolve("dokka")) +} +``` + +## Configuration options + +Dokka documents single-platform as well as multi-platform projects. +Most of the configuration options are set per one source set. +The available configuration options for are shown below: + +```kotlin +dokkaHtml { + outputDirectory.set(buildDir.resolve("dokka")) + + // Set module name displayed in the final output + moduleName.set("moduleName") + + // Use default or set to custom path to cache directory + // to enable package-list caching + // When this is set to default, caches are stored in $USER_HOME/.cache/dokka + cacheRoot.set(file("default")) + dokkaSourceSets { + configureEach { // Or source set name, for single-platform the default source sets are `main` and `test` + + // Used when configuring source sets manually for declaring which source sets this one depends on + dependsOn("otherSourceSetName") + + // Used to remove a source set from documentation, test source sets are suppressed by default + suppress.set(false) + + // Use to include or exclude non public members + includeNonPublic.set(false) + + // Do not output deprecated members. Applies globally, can be overridden by packageOptions + skipDeprecated.set(false) + + // Emit warnings about not documented members. Applies globally, also can be overridden by packageOptions + reportUndocumented.set(true) + + // Do not create index pages for empty packages + skipEmptyPackages.set(true) + + // This name will be shown in the final output + displayName.set("JVM") + + // Platform used for code analysis. See the "Platforms" section of this readme + platform.set(org.jetbrains.dokka.Platform.jvm) + + // Property used for manual addition of files to the classpath + // This property does not override the classpath collected automatically but appends to it + classpath.from(file("libs/dependency.jar")) + + // List of files with module and package documentation + // https://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation + includes.from("packages.md", "extra.md") + + // List of files or directories containing sample code (referenced with @sample tags) + samples.from("samples/basic.kt", "samples/advanced.kt") + + // By default, sourceRoots are taken from Kotlin Plugin and kotlinTasks, following roots will be appended to them + // Repeat for multiple sourceRoots + sourceRoot.from(file("src")) + + // Specifies the location of the project source code on the Web. + // If provided, Dokka generates "source" links for each declaration. + // Repeat for multiple mappings + sourceLink { + // Unix based directory relative path to the root of the project (where you execute gradle respectively). + localDirectory.set(file("src/main/kotlin")) + + // URL showing where the source code can be accessed through the web browser + remoteUrl.set(java.net.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 + remoteLineSuffix.set("#L") + } + + // Used for linking to JDK documentation + jdkVersion.set(8) + + // Disable linking to online kotlin-stdlib documentation + noStdlibLink.set(false) + + // Disable linking to online JDK documentation + noJdkLink.set(false) + + // Disable linking to online Android documentation (only applicable for Android projects) + noAndroidSdkLink.set(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 = URL("https://example.com/docs/") + + // If package-list file is located in non-standard location + // packageListUrl = URL("file:///home/user/localdocs/package-list") + } + + // Allows to customize documentation generation options on a per-package basis + // Repeat for multiple packageOptions + perPackageOption { + prefix.set("kotlin") // will match kotlin and all sub-packages of it + // All options are optional, default values are below: + skipDeprecated.set(false) + reportUndocumented.set(true) // Emit warnings about not documented members + includeNonPublic.set(false) + } + // Suppress a package + perPackageOption { + prefix.set("kotlin.internal") // will match kotlin.internal and all sub-packages of it + suppress.set(true) + } + } + } +} +``` + +## Multiplatform +Dokka supports single-platform and multi-platform projects using source sets abstraction. For most mutli-platform projects +you should assume that dokka's source sets correspond to Kotlin plugin's source sets. All source sets are by default registered +and configured automatically although test source sets are suppressed + +Kotlin +```kotlin +kotlin { // Kotlin Multiplatform plugin configuration + jvm() + js("customName") +} + +tasks.withType<DokkaTask>().configureEach { + // custom output directory + outputDirectory.set(buildDir.resolve("dokka")) + + dokkaSourceSets { + named("customNameMain") { // The same name as in Kotlin Multiplatform plugin, so the sources are fetched automatically + includes.from("packages.md", "extra.md") + samples.from("samples/basic.kt", "samples/advanced.kt") + } + + register("differentName") { // Different name, so source roots must be passed explicitly + displayName = "JVM" + platform = "jvm" + sourceRoots.from(kotlin.sourceSets.getByName("jvmMain").kotlin.srcDirs) + sourceRoots.from(kotlin.sourceSets.getByName("commonMain").kotlin.srcDirs) + } + } + } +``` + +!!! note + If you want to share the configuration between source sets, you can use Gradle's `configureEach` + +## Applying plugins +Dokka plugin creates Gradle configuration for each output format in the form of `dokka${format}Plugin`: + +```kotlin +dependencies { + dokkaHtmlPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:1.4.0-rc") +} +``` + +You can also create a custom dokka task and add plugins directly inside: + +```kotlin +val customDokkaTask by creating(DokkaTask::class) { + dependencies { + plugins("org.jetbrains.dokka:kotlin-as-java-plugin:1.4.0-rc") + } +} +``` + +!!! important + Please note that `dokkaJavadoc` task will properly document only single `jvm` source set + +To generate the documentation, use the appropriate `dokka${format}` Gradle task: + +```bash +./gradlew dokkaHtml +``` + +## Android + +!!! important + Make sure you apply dokka after `com.android.library` and `kotlin-android`. + +```kotlin +buildscript { + repositories { + jcenter() + } + dependencies { + classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:${kotlin_version}") + classpath("org.jetbrains.dokka:dokka-gradle-plugin:${dokka_version}") + } +} +repositories { + jcenter() +} +apply(plugin= "com.android.library") +apply(plugin= "kotlin-android") +apply(plugin= "org.jetbrains.dokka") +``` + +```kotlin +dokkaHtml.configure { + dokkaSourceSets { + named("main") { + noAndroidSdkLink.set(false) + } + } +} +``` + +## Multi-module projects +For documenting Gradle multi-module projects, you can use `dokka${format}Multimodule` tasks. + +```kotlin +tasks.dokkaHtmlMultiModule.configure { + outputDirectory.set(buildDir.resolve("dokkaCustomMultiModuleOutput")) + documentationFileName.set("README.md") +} +``` + +`DokkaMultiModule` depends on all dokka tasks in the subprojects, runs them, and creates a toplevel page (based on the `documentationFile`) +with links to all generated (sub)documentations + +## Example project + +Please see the [Dokka Gradle example project](https://github.com/Kotlin/kotlin-examples/tree/master/gradle/dokka/dokka-gradle-example) for an example. diff --git a/docs/src/doc/docs/user_guide/introduction.md b/docs/src/doc/docs/user_guide/introduction.md new file mode 100644 index 00000000..1add9e9f --- /dev/null +++ b/docs/src/doc/docs/user_guide/introduction.md @@ -0,0 +1,73 @@ +# Introduction + +## Plugins +Dokka can be customized with plugins. Each output format is internally a plugin. +Additionally, `kotlin-as-java` plugin can be used to generate documentation as seen from Java perspective. +Currently maintained plugins are: + +* `dokka-base` - the main plugin needed to run dokka, contains html format +* `gfm-plugin` - configures `GFM` output format +* `jekyll-plugin` - configures `Jekyll` output format +* `javadoc-plugin` - configures `Javadoc` output format, automatically applies `kotlin-as-java-plugin` +* `kotlin-as-java-plugin` - translates Kotlin definitions to Java + +Please see the usage instructions for each build system on how to add plugins to dokka. + +## Source sets +Dokka generates documentation based on source sets. + +For single-platform & multi-platform projects, source sets are the same as in Kotlin plugin: + + * One source set for each platform, eg. `jvmMain` or `jsMain`; + * One source set for each common source set, eg. the default `commonMain` and custom ones like `jsAndJvmMain`. + +When configuring multi-platform projects manually (eg. in the CLI or in Gradle without the Kotlin Gradle Plugin) +source sets must declare their dependent source sets. +Eg. in the following Kotlin plugin configuration: + +* `jsMain` and `jvmMain` both depend on `commonMain` (by default and transitively) and `jsAndJvmMain`; +* `linuxX64Main` only depends on `commonMain`. + +```kotlin +kotlin { // Kotlin plugin configuration + jvm() + js() + linuxX64() + + sourceSets { + val commonMain by getting {} + val jvmAndJsSecondCommonMain by creating { dependsOn(commonMain) } + val jvmMain by getting { dependsOn(jvmAndJsSecondCommonMain) } + val jsMain by getting { dependsOn(jvmAndJsSecondCommonMain) } + val linuxX64Main by getting { dependsOn(commonMain) } + } +} +``` + +## Output formats + Dokka documents Java classes as seen in Kotlin by default, with javadoc format being the only exception. + + * `html` - HTML format used by default + * `javadoc` - looks like JDK's Javadoc, Kotlin classes are translated to Java + * `gfm` - GitHub flavored markdown + * `jekyll` - Jekyll compatible markdown + +If you want to generate the documentation as seen from Java perspective, you can add the `kotlin-as-java` plugin +to the dokka plugins classpath, eg. in Gradle: + +```kotlin +dependencies{ + implementation("...") + dokkaGfmPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:${dokka-version}") +} +``` + +## Platforms + +Each dokka source set is analyzed for a specific platform. The platform should be extracted automatically from the Kotlin plugin. +In case of a manual source set configuration, you have to select one of the following: + + * `jvm` + * `js` + * `native` + * `common` 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. diff --git a/docs/src/doc/mkdocs.yml b/docs/src/doc/mkdocs.yml new file mode 100644 index 00000000..fd226c61 --- /dev/null +++ b/docs/src/doc/mkdocs.yml @@ -0,0 +1,64 @@ +site_name: dokka + +# Meta tags (placed in header) +site_description: Dokka is a documentation engine for Kotlin, performing the same function as javadoc for Java +site_author: Jetbrains +site_url: https://github.com/Kotlin/dokka + +# Repository (add link to repository on each page) +repo_name: dokka +repo_url: https://github.com/Kotlin/dokka +#edit_uri: edit/master/src/doc/docs/ + +# Copyright (shown at the footer) +copyright: 'Copyright © 2020 Jetbrains' + +# Material theme +theme: + name: 'material' + favicon: favicon.svg + social: + - type: 'github' + link: 'https://github.com/Kotlin/dokka' + +# Extensions +markdown_extensions: + - admonition + - codehilite: + guess_lang: false + - footnotes + - meta + - def_list + - toc: + permalink: true + - pymdownx.betterem: + smart_enable: all + - pymdownx.caret + - pymdownx.inlinehilite + - pymdownx.magiclink + - pymdownx.smartsymbols + - pymdownx.superfences + +# Dev server binding +#dev_addr: 127.0.0.1:3001 + +nav: + - Home: index.md + - User guide: + - Introduction: user_guide/introduction.md + - Gradle: user_guide/gradle/usage.md + - Maven: user_guide/maven/usage.md + - Command line: user_guide/cli/usage.md + - Plugin development: + - Introduction: developer_guide/introduction.md + - Data model: developer_guide/data_model.md + - Extension points: developer_guide/extension_points.md + - About: + - FAQ: about/FAQ.md + - Slack channel: about/slack_channel.md + +extra_javascript: + - expand_navigation.js + +extra_css: + - dokka_colors.css diff --git a/settings.gradle.kts b/settings.gradle.kts index d714b676..f40e88d8 100644 --- a/settings.gradle.kts +++ b/settings.gradle.kts @@ -30,6 +30,8 @@ include("integration-tests:maven") include("test-utils") +include("docs") + pluginManagement { val kotlin_version: String by settings plugins { |
