Skip to content

Commit

Permalink
Address review comments
Browse files Browse the repository at this point in the history
  • Loading branch information
@IgnatBeresnev
IgnatBeresnev committed Nov 16, 2022
1 parent 013bc04 commit ccd0b86
Show file tree
Hide file tree
Showing 7 changed files with 191 additions and 72 deletions.
16 changes: 8 additions & 8 deletions docs/topics/formats/html.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -164,14 +164,14 @@ For details, see [configuring Dokka plugins](plugins_introduction.md#configuring

### Configuration options

| **Option** | **Description** |
|-----------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `customAssets` | List of paths for image assets to be bundled with documentation. Can have any extension. See [modifying assets](#customizing-assets) section for details. |
| `customStyleSheets` | List of paths for `.css` stylesheets to be bundled with documentation and used for rendering. See [modifying styles](#customizing-styles) section for details. |
| `footerMessage` | Text displayed in the footer. |
| `separateInheritedMembers` | Boolean property. If set to `true`, Dokka will render properties/functions and inherited properties/inherited functions separately. Disabled by default. |
| `templatesDir` | Path to the directory with custom HTML templates. See [templates](#templates) section for more details. |
| `mergeImplicitExpectActualDeclarations` | Boolean property. If set to true, Dokka will merge declarations that are not declared as expect/actual, but have the same fully qualified name. Can be useful in legacy codebases. Disabled by default. |
| **Option** | **Description** |
|-----------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `customAssets` | List of paths for image assets to be bundled with documentation. Can have any extension. See [modifying assets](#customizing-assets) section for details. |
| `customStyleSheets` | List of paths for `.css` stylesheets to be bundled with documentation and used for rendering. See [modifying styles](#customizing-styles) section for details. |
| `footerMessage` | Text displayed in the footer. |
| `separateInheritedMembers` | Boolean property. If set to `true`, Dokka will render properties/functions and inherited properties/inherited functions separately. Disabled by default. |
| `templatesDir` | Path to the directory with custom HTML templates. See [templates](#templates) section for more details. |
| `mergeImplicitExpectActualDeclarations` | Boolean property. If set to true, Dokka will merge declarations that are not declared as [expect/actual](https://kotlinlang.org/docs/multiplatform-connect-to-apis.html), but have the same fully qualified name. Can be useful in legacy codebases. Disabled by default. |


## Customization
Expand Down
96 changes: 94 additions & 2 deletions docs/topics/overview.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,10 +12,102 @@ multiple flavours of [Markdown](markdown.md) and Java's [Javadoc HTML](javadoc.m
Libraries that use Dokka for API reference docs:

* [kotlinx.coroutines](https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/)
* [detekt](https://detekt.dev/kdoc/detekt-api/io.gitlab.arturbosch.detekt.api/index.html)
* [Bitmovin](https://cdn.bitmovin.com/player/android/3/docs/index.html)
* [Hexagon](https://hexagonkt.com/api/index.html)
* [Ktor](https://api.ktor.io/)
* [Spring Framework](https://docs.spring.io/spring-framework/docs/current/kdoc-api/)
* [OkHttp](https://square.github.io/okhttp/4.x/okhttp/okhttp3/) (Markdown)

Dokka can be run via [Gradle](gradle.md), [Maven](maven.md) or [command line](cli.md). It is also
[highly pluggable](plugins_introduction.md).

## Quickstart

<tabs group="build-script">
<tab title="Gradle Kotlin DSL" group-key="kotlin">

Apply Dokka Gradle plugin in the root project:

```kotlin
plugins {
id("org.jetbrains.dokka") version "%dokkaVersion%"
}
```

When documenting [multi-project](gradle.md#multi-project-builds) builds, you need to apply Dokka in subprojects as well:

```kotlin
subprojects {
apply(plugin = "org.jetbrains.dokka")
}
```

To generate documentation run the following Gradle tasks:

* `dokkaHtml` for single-project builds.
* `dokkaHtmlMultiModule` for multi-module builds.

By default, output directory is set to `/build/dokka/html` and `/build/dokka/htmlMultiModule`.

Learn more about Gradle configuration in a separate [topic dedicated to Gradle](gradle.md).

</tab>
<tab title="Gradle Groovy DSL" group-key="groovy">

Apply Dokka Gradle plugin in the root project:

```groovy
plugins {
id 'org.jetbrains.dokka' version '%dokkaVersion%'
}
```

When documenting [multi-project](gradle.md#multi-project-builds) builds, you need to apply Dokka in subprojects as well:

```groovy
subprojects {
apply plugin: 'org.jetbrains.dokka'
}
```

To generate documentation run the following Gradle tasks:

* `dokkaHtml` for single-project builds.
* `dokkaHtmlMultiModule` for multi-module builds.

By default, output directory is set to `/build/dokka/html` and `/build/dokka/htmlMultiModule`.

Learn more about Gradle configuration in a separate [topic dedicated to Gradle](gradle.md).

</tab>
<tab title="Maven" group-key="mvn">

Add Dokka Maven plugin to the plugins section of your POM:

```xml
<build>
<plugins>
<plugin>
<groupId>org.jetbrains.dokka</groupId>
<artifactId>dokka-maven-plugin</artifactId>
<version>%dokkaVersion%</version>
<executions>
<execution>
<phase>pre-site</phase>
<goals>
<goal>dokka</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
```

To generate documentation run `dokka:dokka` goal.

By default, output directory is set to `target/dokka`.

Learn more about Maven configuration in a separate [topic dedicated to Maven](maven.md).

</tab>
</tabs>
10 changes: 10 additions & 0 deletions docs/topics/plugins/plugins_introduction.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,11 @@ dependencies {
}
```

> When documenting [multi-project](gradle.md#multi-project-builds) builds, you need to apply Dokka plugins in
> subprojects as well as in their parent project.
>
{type="note"}

</tab>
<tab title="Groovy" group-key="groovy">

Expand All @@ -63,6 +68,11 @@ dependencies {
}
```

> When documenting [multi-project](gradle.md#multi-project-builds) builds, you need to apply Dokka plugins in
> subprojects as well as in their parent project.
>
{type="note"}

</tab>
<tab title="Maven" group-key="mvn">

Expand Down
18 changes: 14 additions & 4 deletions docs/topics/plugins/versioning.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,11 @@ dependencies {
}
```

> When documenting [multi-project](gradle.md#multi-project-builds) builds, you need to apply versioning plugin in
> subprojects as well as in their parent project.
>
{type="note"}

</tab>
<tab title="Groovy" group-key="groovy">

Expand All @@ -31,6 +36,11 @@ dependencies {
}
```

> When documenting [multi-project](gradle.md#multi-project-builds) builds, you need to apply versioning plugin in
> subprojects as well as in their parent project.
>
{type="note"}

</tab>
<tab title="Maven" group-key="mvn">

Expand Down Expand Up @@ -90,7 +100,7 @@ Via [JSON configuration](cli.md#running-with-json-configuration):

Versioning plugin has a number of optional configuration properties:

| **Task** | **Description** |
| **Property** | **Description** |
|--------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `version` | Version of your application/library for which documentation is going to be generated. This will be the version in the dropdown menu. |
| `versionsOrdering` | Optional list of strings that represents the order in which versions should appear in the dropdown. Must match version string exactly. First item of the list is the topmost in the dropdown. |
Expand Down Expand Up @@ -242,9 +252,9 @@ Alternatively, via JSON configuration:

With versioning plugin applied and configured, no other steps are needed: documentation can be built the usual way.

Versioning plugin will add a `version.json` file to the output folder. This file will be used by the plugin to match
versions and generate version navigation. If your previously generated documentation does not have that file, you
may need to re-generate it.
Among other things, versioning plugin will add a `version.json` file to the output folder. This file will be used by the
plugin to match versions and generate version navigation. If your previously generated documentation does not have that
file, you will need to re-generate documentation for such versions -- adding just the file will not work.

Versioning plugin will also bundle all other documentation versions that have been passed through `olderVersionsDir`
and `olderVersions` configuration properties by putting them inside `older` directory.
Expand Down
4 changes: 2 additions & 2 deletions docs/topics/runners/cli.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -116,12 +116,12 @@ See [JSON configuration options](#json-configuration) for more details.

### Other output formats

By default, `dokka-base` artifact contains [HTML](html.md) format only.
By default, `dokka-base` artifact contains stable [HTML](html.md) format only.

All other output formats come as [Dokka plugins](plugins_introduction.md). In order to use them, you have to put it
on plugins classpath.

For example, if you want to generate documentation in [GFM](markdown.md#gfm) format, you have to download and
For example, if you want to generate documentation in experimental [GFM](markdown.md#gfm) format, you have to download and
pass [gfm-plugin's jar](https://mvnrepository.com/artifact/org.jetbrains.dokka/gfm-plugin/%dokkaVersion%) into
`pluginsClasspath` configuration option.

Expand Down
93 changes: 49 additions & 44 deletions docs/topics/runners/gradle.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -62,46 +62,10 @@ plugins {
>
{type="note"}


### Legacy plugin application

If you cannot use plugins DSL for some reason, you can use
[the legacy method](https://docs.gradle.org/current/userguide/plugins.html#sec:old_plugin_application) of applying
plugins.

<tabs group="build-script">
<tab title="Kotlin" group-key="kotlin">

```kotlin
buildscript {
dependencies {
classpath("org.jetbrains.dokka:dokka-gradle-plugin:%dokkaVersion%")
}
}

apply(plugin="org.jetbrains.dokka")
```

> Note that by applying Dokka this way, certain type-safe accessors will not be available in Kotlin DSL.
>
{type="note"}

</tab>
<tab title="Groovy" group-key="groovy">

```groovy
buildscript {
dependencies {
classpath 'org.jetbrains.dokka:dokka-gradle-plugin:%dokkaVersion%'
}
}
apply plugin: 'org.jetbrains.dokka'
```

</tab>
</tabs>

## Generating documentation

Dokka's Gradle plugin comes with [HTML](html.md), [Markdown](markdown.md) and [Javadoc](javadoc.md) formats built in,
Expand All @@ -111,9 +75,16 @@ and adds a number of tasks for generating documentation, both for [single](#sing

Use the following tasks to build documentation for simple, single project applications and libraries:

#### Stable formats

| **Task** | **Description** |
|----------------|-------------------------------------------------------------------------------------|
| `dokkaHtml` | Generates documentation in [HTML](html.md) format. |

#### Experimental formats

| **Task** | **Description** |
|----------------|-------------------------------------------------------------------------------------|
| `dokkaGfm` | Generates documentation in [GitHub Flavored Markdown](markdown.md#gfm) format. |
| `dokkaJavadoc` | Generates documentation in [Javadoc](javadoc.md) format. |
| `dokkaJekyll` | Generates documentation in [Jekyll compatible Markdown](markdown.md#jekyll) format. |
Expand All @@ -123,12 +94,50 @@ Output location, among other things, can be [configured](#configuration) separat

### Multi-project builds

For documenting [multi-project builds](https://docs.gradle.org/current/userguide/multi_project_builds.html), you can
use tasks which are created for all parent projects automatically:
For documenting [multi-project builds](https://docs.gradle.org/current/userguide/multi_project_builds.html), you need
to apply the Dokka plugin in subprojects that you want to generate documentation for as well as in their parent project.

You can use `allprojects {}` and `subprojects {}` Gradle configurations to achieve that:

<tabs group="build-script">
<tab title="Kotlin" group-key="kotlin">

```kotlin
subprojects {
apply(plugin = "org.jetbrains.dokka")
}
```

</tab>
<tab title="Groovy" group-key="groovy">

```groovy
subprojects {
apply plugin: 'org.jetbrains.dokka'
}
```

</tab>
</tabs>

#### MultiModule tasks

`MultiModule` tasks generate documentation for each subproject individually via [partial](#partial-tasks) tasks,
collect and process all outputs, and produce complete documentation with a common table of contents and resolved
cross-project references.

Dokka creates the following tasks for **parent** projects automatically:

#### Stable formats

| **Task** | **Description** |
|--------------------------|--------------------------------------------------------------------------------------------------|
| `dokkaHtmlMultiModule` | Generates multi-module documentation in [HTML](html.md) format. |

#### Experimental formats

| **Task** | **Description** |
|--------------------------|--------------------------------------------------------------------------------------------------|
| `dokkaGfmMultiModule` | Generates multi-module documentation in [GitHub Flavored Markdown](markdown.md#gfm) format. |
| `dokkaJekyllMultiModule` | Generates multi-module documentation in [Jekyll compatible Markdown](markdown.md#jekyll) format. |

Expand All @@ -137,13 +146,9 @@ use tasks which are created for all parent projects automatically:
>
{type="note"}

A _MultiModule_ task generates documentation for each subproject individually via [partial](#partial-tasks) tasks,
collects and processes all outputs, and produces complete documentation with a common table of contents and resolved
cross-project references.

By default, you will find ready-to-use documentation under `{parentProject}/build/dokka/{format}MultiModule` directory.

##### MultiModule task example
#### MultiModule task example

Given a project with the following structure:

Expand Down Expand Up @@ -287,7 +292,7 @@ tasks.dokkaHtmlPartial {
}
```

If you applied Dokka with the [buildscript block](#legacy-plugin-application):
If you applied Dokka with the [buildscript block](https://docs.gradle.org/current/userguide/plugins.html#sec:old_plugin_application):

```kotlin
import org.jetbrains.dokka.gradle.DokkaTask
Expand Down
Loading

0 comments on commit ccd0b86

Please sign in to comment.