Skip to content

Commit

Permalink
technical writer review
Browse files Browse the repository at this point in the history
  • Loading branch information
@sarahhaggarty
sarahhaggarty committed Dec 15, 2022
1 parent de65b72 commit 197bf14
Show file tree
Hide file tree
Showing 10 changed files with 594 additions and 577 deletions.
38 changes: 23 additions & 15 deletions docs/README.md
View file
@@ -1,30 +1,36 @@
# docs
# Dokka documentation

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

Documentation format is basically markdown with some DSL that is used internally at JetBrains.
Our documentation is written in Markdown format with some domain specific language (DSL) that is used at JetBrains.

## Project structure

* `dokka.tree` represents Table of Contents
* `vars.list` contains variables that you can use throughout documentation
* `topics` directory contains documentation topics themselves
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
## DSL guide

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

### Title

Each page must have a title. By default, this title is used in ToC as well.
To declare the title of your document:

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

Note that title is basically a level 1 header, and it has to be the only one. So all other headers within topics must
be at least level 2, otherwise sidebar navigation may not work as expected.
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
>
Expand All @@ -33,6 +39,8 @@ be at least level 2, otherwise sidebar navigation may not work as expected.

### Tips

To add a tip:

```text
> This is a useful tip
>
Expand All @@ -41,6 +49,8 @@ be at least level 2, otherwise sidebar navigation may not work as expected.

### Warning

To add a warning:

```text
> This is a warning
>
Expand All @@ -49,9 +59,9 @@ be at least level 2, otherwise sidebar navigation may not work as expected.

### Tabs

Tabs can be used to give instructions that are specific to a build system or something else.
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 inside tabs is not limited to just text - it can be code blocks, tips, etc.
Content within tabs isn't limited to text. You can also add code blocks, tips, etc.

```text
<tabs group="build-script">
Expand All @@ -75,9 +85,7 @@ Instructions specific to CLI
</tabs>
```

Notice the use of `group-key` - this groups all tabs on the page, and when the user switches to a tab - it switches to
all tabs with this key throughout the whole page. This is convenient for the user, since if they switched to Groovy tab,
they probably want other tabs to be of that value as well.
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

Expand Down
123 changes: 61 additions & 62 deletions docs/topics/formats/html.md
View file

Large diffs are not rendered by default.

46 changes: 23 additions & 23 deletions docs/topics/formats/javadoc.md
View file
@@ -1,49 +1,49 @@
[//]: # (title: Javadoc)

> Javadoc output format is still in Alpha, use at your own risk, expect bugs and migration issues. Correct
> integration with tools that accept Java's Javadoc HTML as input is not guaranteed.
> The Javadoc output format is still in Alpha so you may find bugs and experience migration issues when using it. **You use it at your own risk.**
> Successful integration with tools that accept Java's Javadoc HTML as input is not guaranteed.
>
{type="warning"}

Dokka's Javadoc output format is a lookalike of Java's
Dokka's Javadoc output format is similar to Java's
[Javadoc HTML format](https://docs.oracle.com/en/java/javase/19/docs/api/index.html).

It tries to visually mimic HTML pages generated by the Javadoc tool, but it's not a direct implementation
and it's not an exact copy.
It tries to visually mimic HTML pages generated by the Javadoc tool, but it's not a direct implementation
or an exact copy.

![Screenshot of javadoc output format](javadoc-format-example.png){height=750}

All Kotlin code and signatures are rendered as seen from Java's perspective, this is achieved with
All Kotlin code and signatures are rendered as seen from Java's perspective. This is achieved with our
[Kotlin as Java plugin](https://github.com/Kotlin/dokka/tree/master/plugins/kotlin-as-java), which comes bundled and
applied by default for this format.

Javadoc output format is a rendering [Dokka plugin](plugins_introduction.md), maintained by the Dokka team.
It is [open source](https://github.com/Kotlin/dokka/tree/master/plugins/javadoc).
The Javadoc output format is generated by our [Dokka plugin](plugins_introduction.md), which we actively maintain.
It is open source and you can find the source code on [GitHub](https://github.com/Kotlin/dokka/tree/master/plugins/javadoc).

## Geneatring Javadoc documentation
## Generating Javadoc documentation

> Javadoc format does not support multiplatform projects.
> The Javadoc format is not supported for multiplatform projects.
>
{type="note"}
{type="warning"}


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

Dokka's [Gradle plugin](gradle.md) ships with Javadoc format included, you can use the following tasks:
Dokka's [Gradle plugin](gradle.md) comes with the Javadoc output format included. You can use the following tasks:

| **Task** | **Description** |
|-------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `dokkaJavadoc` | Generates Javadoc documentation for a single project. |
| `dokkaJavadocCollector` | A [Collector](gradle.md#collector-tasks) task created only for parent projects in multi-project builds. Calls `dokkaJavadoc` for every subproject and merges all outputs into a single virtual project. |
| **Task** | **Description** |
|-------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `dokkaJavadoc` | Generates Javadoc documentation for a single project. |
| `dokkaJavadocCollector` | A [Collector](gradle.md#collector-tasks) task created only for parent projects in multi-project builds. It calls `dokkaJavadoc` for every subproject and merges all outputs into a single virtual project. |

`javadoc.jar` [can be built separately](gradle.md#building-javadoc-jar).
The `javadoc.jar` file can be generated separately. For more information, see [Building `javadoc.jar`](gradle.md#building-javadoc-jar).

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

Dokka's [Maven plugin](maven.md) ships with Javadoc format built in, you can generate documentation
with the following goals:
Dokka's [Maven plugin](maven.md) comes with the Javadoc output format built in. You can generate documentation
by using the following goals:

| **Goal** | **Description** |
|--------------------|------------------------------------------------------------------------------|
Expand All @@ -54,10 +54,10 @@ with the following goals:
</tab>
<tab title="CLI" group-key="cli">

Since Javadoc format is a [Dokka plugin](plugins_introduction.md#applying-dokka-plugins), you need to download the
[jar file](https://mvnrepository.com/artifact/org.jetbrains.dokka/javadoc-plugin/%dokkaVersion%).
Since the Javadoc output format is generated by a [Dokka plugin](plugins_introduction.md#applying-dokka-plugins), you need to download the plugin as a
[JAR file](https://mvnrepository.com/artifact/org.jetbrains.dokka/javadoc-plugin/%dokkaVersion%).

Javadoc format has two dependencies that you will need to provide as jar files as well:
The Javadoc output format has two dependencies that you need to provide as additional JAR files:

* [kotlin-as-java plugin](https://mvnrepository.com/artifact/org.jetbrains.dokka/kotlin-as-java-plugin/%dokkaVersion%)
* [korte-jvm](https://mvnrepository.com/artifact/com.soywiz.korlibs.korte/korte-jvm/3.3.0)
Expand Down Expand Up @@ -86,7 +86,7 @@ Via [JSON configuration](cli.md#running-with-json-configuration):
}
```

For more information, see [other output formats](cli.md#other-output-formats) section for the CLI runner.
For more information, see [Other output formats](cli.md#other-output-formats) in the CLI runner documentation.

</tab>
</tabs>
46 changes: 23 additions & 23 deletions docs/topics/formats/markdown.md
View file
@@ -1,6 +1,6 @@
[//]: # (title: Markdown)

> Markdown output formats are still in Alpha, use at your own risk, expect bugs and migration issues.
> The Markdown output formats are still in Alpha so you may find bugs and experience migration issues when using them. **You use them at your own risk.**
>
{type="warning"}

Expand All @@ -15,18 +15,18 @@ they are open source.

## GFM

GFM format generates documentation in [GitHub Flavored Markdown](https://github.github.com/gfm/).
The GFM output format generates documentation in [GitHub Flavored Markdown](https://github.github.com/gfm/).

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

Dokka's [Gradle plugin](gradle.md) ships with GFM format included, you can use the following tasks:
Dokka's [Gradle plugin](gradle.md) comes with the GFM output format included. You can use the following tasks with it:

| **Task** | **Description** |
|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `dokkaGfm` | Generates GFM documentation for a single project. |
| `dokkaGfmMultiModule` | A [MultiModule](gradle.md#multi-project-builds) task created only for parent projects in multi-project builds. Generates documentation for subprojects and collects all outputs in a single place with a common table of contents. |
| `dokkaGfmCollector` | A [Collector](gradle.md#collector-tasks) task created only for parent projects in multi-project builds. Calls `dokkaGfm` for every subproject and merges all outputs into a single virtual project. |
| **Task** | **Description** |
|-----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `dokkaGfm` | Generates GFM documentation for a single project. |
| `dokkaGfmMultiModule` | A [MultiModule](gradle.md#multi-project-builds) task created only for parent projects in multi-project builds. It generates documentation for subprojects and collects all outputs in a single place with a common table of contents. |
| `dokkaGfmCollector` | A [Collector](gradle.md#collector-tasks) task created only for parent projects in multi-project builds. It calls `dokkaGfm` for every subproject and merges all outputs into a single virtual project. |

</tab>
<tab title="Maven" group-key="groovy">
Expand All @@ -51,9 +51,9 @@ dependency:
</plugin>
```

After that, running `dokka:dokka` goal should produce documentation in GFM format.
After configuring this, running the `dokka:dokka` goal produces documentation in GFM format.

For more information, see [other output formats](maven.md#other-output-formats) section for the Maven plugin.
For more information, see the Mavin plugin documentation for [Other output formats](maven.md#other-output-formats).

</tab>
<tab title="CLI" group-key="cli">
Expand Down Expand Up @@ -84,27 +84,27 @@ Via [JSON configuration](cli.md#running-with-json-configuration):
}
```

For more information, see [other output formats](cli.md#other-output-formats) section for the CLI runner.
For more information, see the CLI runner documentation for [Other output formats](cli.md#other-output-formats).

</tab>
</tabs>

You can find sources [on GitHub](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/plugins/gfm).
You can find the source code [on GitHub](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/plugins/gfm).

## Jekyll

Jekyll format generates documentation in [Jekyll](https://jekyllrb.com/) compatible Markdown.
The Jekyll output format generates documentation in [Jekyll](https://jekyllrb.com/) compatible Markdown.

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

Dokka's [Gradle plugin](gradle.md) ships with Jekyll format included, you can use the following tasks:
Dokka's [Gradle plugin](gradle.md) comes with the Jekyll output format included. You can use the following tasks with it:

| **Task** | **Description** |
|--------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `dokkaJekyll` | Generates Jekyll documentation for a single project. |
| `dokkaJekyllMultiModule` | A [MultiModule](gradle.md#multi-project-builds) task created only for parent projects in multi-project builds. Generates documentation for subprojects and collects all outputs in a single place with a common table of contents. |
| `dokkaJekyllCollector` | A [Collector](gradle.md#collector-tasks) task created only for parent projects in multi-project builds. Calls `dokkaJekyll` for every subproject and merges all outputs into a single virtual project. |
| **Task** | **Description** |
|--------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `dokkaJekyll` | Generates Jekyll documentation for a single project. |
| `dokkaJekyllMultiModule` | A [MultiModule](gradle.md#multi-project-builds) task created only for parent projects in multi-project builds. It generates documentation for subprojects and collects all outputs in a single place with a common table of contents. |
| `dokkaJekyllCollector` | A [Collector](gradle.md#collector-tasks) task created only for parent projects in multi-project builds. It calls `dokkaJekyll` for every subproject and merges all outputs into a single virtual project. |

</tab>
<tab title="Maven" group-key="groovy">
Expand All @@ -129,9 +129,9 @@ dependency:
</plugin>
```

After that, running `dokka:dokka` goal should produce documentation in GFM format.
After configuring this, running the `dokka:dokka` goal produces documentation in GFM format.

For more information, see [other output formats](maven.md#other-output-formats) section for the Maven plugin.
For more information, see the Maven plugin documentation for [Other output formats](maven.md#other-output-formats).

</tab>
<tab title="CLI" group-key="cli">
Expand Down Expand Up @@ -164,9 +164,9 @@ Via [JSON configuration](cli.md#running-with-json-configuration):
}
```

For more information, see [other output formats](cli.md#other-output-formats) section for the CLI runner.
For more information, see the CLI runner documentation for [Other output formats](cli.md#other-output-formats).

</tab>
</tabs>

You can find sources [on GitHub](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/plugins/jekyll).
You can find the source code on [GitHub](https://github.com/Kotlin/dokka/tree/%dokkaVersion%/plugins/jekyll).

0 comments on commit 197bf14

Please sign in to comment.