Skip to content

Commit

Permalink
Fix review comments and proofread documentation once more
Browse files Browse the repository at this point in the history
  • Loading branch information
@IgnatBeresnev
IgnatBeresnev committed Dec 22, 2022
1 parent ba31f35 commit 2c17ae0
Show file tree
Hide file tree
Showing 16 changed files with 528 additions and 865 deletions.
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
View file
Expand Up @@ -29,7 +29,7 @@ Here's how to import and configure Dokka in IntelliJ IDEA:

If you want to use/test your locally built Dokka in a project, do the following:
1. Change `dokka_version` in `gradle.properties` to something that you will use later on as the dependency version.
For instance, you can set it to something like `1.7.20-my-fix-SNAPSHOT`.
For example, you can set it to something like `1.7.20-my-fix-SNAPSHOT`.
2. Publish it to maven local (`./gradlew publishToMavenLocal`)
3. In the project you want to generate documentation for, add maven local as a plugin/dependency
repository (`mavenLocal()`)
Expand Down
95 changes: 4 additions & 91 deletions docs/README.md
View file
Expand Up @@ -2,95 +2,8 @@

This folder contains the Dokka documentation that is available on [kotlinlang.org](https://kotlinlang.org/).

Our documentation is written in Markdown format with some domain specific language (DSL) that is used at JetBrains.
Our documentation is written in Markdown format with some domain specific language (DSL) constructs that are used at
JetBrains.

## Project structure

This project contains:
* A `topics` directory, which contains our documentation in Markdown format.
* A `dokka.tree` file, that describes the site navigation structure.
* A `vars.list` file, that contains a list of variables that you can use throughout documentation.

## DSL guide

This section explains what DSL you can use to create different document elements.

### Title

To declare the title of your document:

```text
[//]: # (title: Name of topic)
```

Every document must have a title. By default, this title is used in the side menu.

As the title is a level 1 header, it must be the only level 1 header in your document. All other headers within your document must be at least level 2, otherwise the side menu may not work as expected.

### Notes

To add a note:

```text
> This is a simple note
>
{type="note"}
```

### Tips

To add a tip:

```text
> This is a useful tip
>
{type="tip"}
```

### Warning

To add a warning:

```text
> This is a warning
>
{type="warning"}
```

### Tabs

Tabs can be used to save space in your document, allowing you to show different text in the same space depending on the tab chosen.

Content within tabs isn't limited to text. You can also add code blocks, tips, etc.

```text
<tabs group="build-script">
<tab title="Kotlin" group-key="kotlin">
Instructions specific to Kotlin
</tab>
<tab title="Groovy" group-key="groovy">
Instructions specific to Groovy
</tab>
<tab title="Maven" group-key="mvn">
Instructions specific to Maven
</tab>
<tab title="CLI" group-key="cli">
Instructions specific to CLI
</tab>
</tabs>
```

You can use the `group-key` parameter to link tabs in a document together. Grouping tabs like this means that if your reader selects a particular tab, e.g. "Groovy", then other tabbed sections in your document will also show the tab for "Groovy" first.

## Documentation preview

Unfortunately, at the moment, to properly preview documentation you need to be a JetBrains employee
or have access to internal infrastructure.

If you do have access, download `Stardust` plugin (ask around for instructions), and on the right sidebar you'll see
`Stardust Article Preview` tab, open it.
If you wish to contribute to the documentation, please read through
[Kotlin documentation guidelines](https://docs.google.com/document/d/1mUuxK4xwzs3jtDGoJ5_zwYLaSEl13g_SuhODdFuh2Dc/edit).
8 changes: 3 additions & 5 deletions docs/dokka.tree
View file
Expand Up @@ -7,7 +7,8 @@
start-page="quickstart.md">

<toc-element id="overview.md"/>
<toc-element toc-title="Runners">
<toc-element id="get_started.md"/>
<toc-element toc-title="Running Dokka">
<toc-element id="gradle.md"/>
<toc-element id="maven.md"/>
<toc-element id="cli.md"/>
Expand All @@ -17,8 +18,5 @@
<toc-element id="markdown.md"/>
<toc-element id="javadoc.md"/>
</toc-element>
<toc-element toc-title="Plugins">
<toc-element id="plugins_introduction.md"/>
<toc-element id="versioning.md"/>
</toc-element>
<toc-element id="dokka_plugins.md"/>
</product-profile>
26 changes: 12 additions & 14 deletions docs/topics/plugins/plugins_introduction.md → docs/topics/dokka_plugins.md
View file
Expand Up @@ -30,7 +30,7 @@ to your project:
<tabs group="build-script">
<tab title="Kotlin" group-key="kotlin">

The Gradle plugin creates convenient dependency configurations that allow you to apply plugins universally or
The Dokka Gradle runner creates convenient dependency configurations that allow you to apply plugins universally or
for a specific output format only.

```kotlin
Expand All @@ -54,7 +54,7 @@ dependencies {
</tab>
<tab title="Groovy" group-key="groovy">

The Gradle plugin creates convenient dependency configurations that allow you to apply Dokka plugins universally or
The Dokka Gradle runner creates convenient dependency configurations that allow you to apply Dokka plugins universally or
for a specific output format only.

```groovy
Expand Down Expand Up @@ -98,7 +98,7 @@ dependencies {
</tab>
<tab title="CLI" group-key="cli">

If you are using the [CLI](cli.md) runner with [command line arguments](cli.md#running-with-command-line-arguments),
If you are using the [CLI](cli.md) runner with [command line options](cli.md#running-with-command-line-options),
Dokka plugins should be passed as `.jar` files to `-pluginsClasspath`:

```Shell
Expand Down Expand Up @@ -127,18 +127,18 @@ If you are using [JSON configuration](cli.md#running-with-json-configuration), D

## Configuring Dokka plugins

Dokka plugins can also have configuration options of their own. Consult each plugin's documentation to see which
options are available.
Dokka plugins can also have configuration options of their own. To see which options are available, consult
documentation of the plugin you want to configure.

Let's have a look at how you can configure the `DokkaBase` plugin, which is responsible for generating [HTML](html.md)
documentation, by adding a custom image to assets (`customAssets` option), by adding custom style sheets
documentation, by adding a custom image to the assets (`customAssets` option), by adding custom style sheets
(`customStyleSheets` option), and by modifying the footer message (`footerMessage` option):

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

Gradle's Kotlin DSL allows for type-safe plugin configuration. This is achievable by adding plugin's artifact to classpath
dependencies in the `buildscript` block, and then importing plugin and configuration classes:
Gradle's Kotlin DSL allows for type-safe plugin configuration. This is achievable by adding the plugin's artifact to
the classpath dependencies in the `buildscript` block, and then importing plugin and configuration classes:

```kotlin
import org.jetbrains.dokka.base.DokkaBase
Expand Down Expand Up @@ -232,8 +232,8 @@ tasks.withType(DokkaTask.class) {
</tab>
<tab title="CLI" group-key="cli">

If you are using the [CLI](cli.md) runner with [command line arguments](cli.md#running-with-command-line-arguments),
use the `-pluginsConfiguration` argument that accepts JSON configuration in the form of `fullyQualifiedPluginName=json`.
If you are using the [CLI](cli.md) runner with [command line options](cli.md#running-with-command-line-options),
use the `-pluginsConfiguration` option that accepts JSON configuration in the form of `fullyQualifiedPluginName=json`.

If you need to configure multiple plugins, you can pass multiple values separated by `^^`.

Expand All @@ -244,7 +244,7 @@ java -jar dokka-cli-%dokkaVersion%.jar \
```

If you are using [JSON configuration](cli.md#running-with-json-configuration), there exists a similar
`pluginsConfiguration` array that accepts JSON as `values`.
`pluginsConfiguration` array that accepts JSON configuration in `values`.

```json
{
Expand All @@ -264,12 +264,10 @@ If you are using [JSON configuration](cli.md#running-with-json-configuration), t

## Notable plugins

For a list of popular Dokka plugins, see the table below.

| **Name** | **Description** |
|-----------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------|
| [Android documentation plugin](https://github.com/Kotlin/dokka/tree/master/plugins/android-documentation) | Improves the documentation experience on Android |
| [Versioning plugin](versioning.md) | Adds version selector and helps to organize documentation for different versions of your application/library |
| [Versioning plugin](https://github.com/Kotlin/dokka/tree/master/plugins/versioning) | Adds version selector and helps to organize documentation for different versions of your application/library |
| [MermaidJS HTML plugin](https://github.com/glureau/dokka-mermaid) | Renders [MermaidJS](https://mermaid-js.github.io/mermaid/#/) diagrams and visualizations found in KDocs |
| [Mathjax HTML plugin](https://github.com/Kotlin/dokka/tree/master/plugins/mathjax) | Pretty prints mathematics found in KDocs |
| [Kotlin as Java plugin](https://github.com/Kotlin/dokka/tree/master/plugins/kotlin-as-java) | Renders Kotlin signatures as seen from Java's perspective |

0 comments on commit 2c17ae0

Please sign in to comment.