Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Revise README documentation for examples and plugins (#2736)
- Loading branch information
1 parent
1fa8552
commit 5eeb2bb
Showing
126 changed files
with
4,594 additions
and
185 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,41 +1,89 @@ | ||
## 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: | ||
* 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 | ||
* Use the default options and select "OK" | ||
* 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 | ||
* Verify the following project settings. In File > Settings > Build, Execution, | ||
Deployment > Build Tools > Gradle > Runner: | ||
* Ensure "Delegate IDE build/run actions to gradle" is checked | ||
* "Gradle Test Runner" should be selected in the "Run tests using" drop-down | ||
menu | ||
* Note: After closing and re-opening the project, IDEA may give an error | ||
message: "Error Loading Project: Cannot load 3 modules". Open up the details | ||
of the error, and click "Remove Selected", as these module `.iml` files are | ||
safe to remove. | ||
|
||
## Using/testing locally built Dokka | ||
|
||
If you want to use/test your locally built Dokka in a project, do the following: | ||
# Contributing Guidelines | ||
|
||
There are three main ways you can contribute to Dokka's development: | ||
|
||
* Submitting issues. | ||
* Submitting fixes/changes/improvements via pull requests. | ||
* Developing community plugins. | ||
|
||
## Submitting issues | ||
|
||
Bug reports, feature requests and questions are welcome. Submit issues [here](https://github.com/Kotlin/dokka/issues). | ||
|
||
* Search for existing issues to avoid reporting duplicates. | ||
* When submitting a bug report: | ||
* Test it against the most recently released version. It might have been fixed already. | ||
* Include code that reproduces the problem. Provide a complete reproducer, yet minimize it as much as | ||
possible. A separate project that can be cloned is ideal. | ||
* If the bug is in behavior, explain what behavior you expected and what the actual result is. | ||
* When submitting a feature request: | ||
* Explain why you need the feature. | ||
* Explaining the problem you face is more important than suggesting a solution. | ||
Report your problem even if you have no proposed solution. | ||
|
||
## Submitting PRs | ||
|
||
Dokka has extensive [Developer Guides](https://kotlin.github.io/dokka/1.7.20/developer_guide/introduction/) documentation | ||
which goes over the development [Workflow](https://kotlin.github.io/dokka/1.7.20/developer_guide/workflow/) and | ||
[Dokka's architecture](https://kotlin.github.io/dokka/1.7.20/developer_guide/architecture/architecture_overview/), | ||
which can help you understand how to achieve what you want and where to look. | ||
|
||
All development (both new features and bugfixes) takes place in the `master` branch, it contains sources for the next | ||
version of Dokka. | ||
|
||
For any code changes: | ||
|
||
* Follow [Kotlin Coding Conventions](https://kotlinlang.org/docs/reference/coding-conventions.html). | ||
Use 4 spaces for indentation. | ||
* [Build the project](#building) to make sure it all works and tests pass. | ||
* Write tests that reproduce the bug or test new features. | ||
* PRs without tests are accepted only in exceptional circumstances if it is evident that writing the | ||
corresponding test is too hard or otherwise impractical. | ||
* If you add new or change old public API, [update public API dump](#updating-public-api-dump), otherwise it will fail | ||
the build. | ||
|
||
Please [contact maintainers](#contacting-maintainers) in advance to coordinate any big piece of work. | ||
|
||
### Building | ||
|
||
Building Dokka is pretty straightforward, with one small caveat: when you run `./gradlew build`, it will run integration | ||
tests as well, which might take some time and will consume a lot of RAM (~20-30 GB), so you would usually want to exclude | ||
integration tests when building locally: | ||
|
||
```Bash | ||
./gradlew build -x integrationTest | ||
``` | ||
|
||
Unit tests which are run as part of `build` should not take much time, but you can also skip it with `-x test`. | ||
|
||
### Using/testing locally built Dokka | ||
|
||
Below you will find a bare-bones instruction on how to use and test locally built Dokka. For more details and examples, | ||
visit [Workflow](https://kotlin.github.io/dokka/1.7.20/developer_guide/workflow/) topic. | ||
|
||
1. Change `dokka_version` in `gradle.properties` to something that you will use later on as the dependency version. | ||
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 | ||
For instance, 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 for which you want to generate documentation add Maven Local as a buildscript/dependency | ||
repository (`mavenLocal()`) | ||
4. Update your dokka dependency to the version you've just published: | ||
4. Update your Dokka dependency to the version you've just published: | ||
|
||
```kotlin | ||
plugins { | ||
id("org.jetbrains.dokka") version "1.7.20-my-fix-SNAPSHOT" | ||
} | ||
``` | ||
|
||
### Updating public API dump | ||
|
||
[Binary Compatibility Validator](https://github.com/Kotlin/binary-compatibility-validator/blob/master/README.md) | ||
is used to keep track of public API changes. | ||
|
||
Run `./gradlew apiDump` to update API index files after introducing new or changing old public API. Commit updated | ||
API indexes together with other changes. | ||
|
||
## Contacting maintainers | ||
|
||
* If something cannot be done, not convenient, or does not work — submit an [issue](#submitting-issues). | ||
* Discussions and general inquiries — use `#dokka` channel in | ||
[Kotlin Community Slack](https://surveys.jetbrains.com/s3/kotlin-slack-sign-up). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,25 @@ | ||
# Dokka examples | ||
|
||
## Gradle | ||
|
||
| Project | Description | | ||
|-------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ||
| [dokka-customFormat-example](gradle/dokka-customFormat-example) | Demonstrates how to override `.css` styles and add custom images as assets, allowing you to change the logo used in the header. | | ||
| [dokka-gradle-example](gradle/dokka-gradle-example) | Demonstrates how to apply Dokka in a simple single-project Gradle build, as well as how to configure it. | | ||
| [dokka-kotlinAsJava-example](gradle/dokka-kotlinAsJava-example) | Demonstrates how to apply Dokka plugins, [Kotlin as Java](../plugins/kotlin-as-java) specifically. | | ||
| [dokka-library-publishing-example](gradle/dokka-library-publishing-example) | Demonstrates how to integrate Dokka into the publishing process of a library, adding documentation generated by Dokka as artifacts. | | ||
| [dokka-multimodule-example](gradle/dokka-multimodule-example) | Demonstrates how to apply and configure Dokka in a [multi-project build](https://docs.gradle.org/current/userguide/multi_project_builds.html). | | ||
| [dokka-multiplatform-example](gradle/dokka-multiplatform-example) | Demonstrates Dokka's configuration and output for a simple [Kotlin Multiplatform](https://kotlinlang.org/docs/multiplatform.html) project. | | ||
| [dokka-versioning-multimodule-example](gradle/dokka-versioning-multimodule-example) | Demonstrates configuration of Dokka's [versioning plugin](../../../plugins/versioning), which allows readers to navigate through different versions of documentation. | | ||
|
||
## Maven | ||
|
||
| Project | Description | | ||
|----------------|-----------------------------------------------------| | ||
| [maven](maven) | Simple Maven project with basic Dokka configuration | | ||
|
||
## Plugins | ||
|
||
| Project | Description | | ||
|-----------------------------------------------|--------------------------------------------------------------------------------------------------------| | ||
| [hide-internal-api](plugin/hide-internal-api) | Dokka plugin that excludes declarations from generated documentation based on an `Internal` annotation | |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,11 @@ | ||
# Gradle examples | ||
|
||
| Project | Description | | ||
|-------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ||
| [dokka-customFormat-example](gradle/dokka-customFormat-example) | Demonstrates how to override `.css` styles and add custom images as assets, allowing you to change the logo used in the header. | | ||
| [dokka-gradle-example](gradle/dokka-gradle-example) | Demonstrates how to apply Dokka in a simple single-project Gradle build, as well as how to configure it. | | ||
| [dokka-kotlinAsJava-example](gradle/dokka-kotlinAsJava-example) | Demonstrates how to apply Dokka plugins, [Kotlin as Java](../plugins/kotlin-as-java) specifically. | | ||
| [dokka-library-publishing-example](gradle/dokka-library-publishing-example) | Demonstrates how to integrate Dokka into the publishing process of a library, adding documentation generated by Dokka as artifacts. | | ||
| [dokka-multimodule-example](gradle/dokka-multimodule-example) | Demonstrates how to apply and configure Dokka in a [multi-project build](https://docs.gradle.org/current/userguide/multi_project_builds.html). | | ||
| [dokka-multiplatform-example](gradle/dokka-multiplatform-example) | Demonstrates Dokka's configuration and output for a simple [Kotlin Multiplatform](https://kotlinlang.org/docs/multiplatform.html) project. | | ||
| [dokka-versioning-multimodule-example](gradle/dokka-versioning-multimodule-example) | Demonstrates configuration of Dokka's [versioning plugin](../../../plugins/versioning), which allows readers to navigate through different versions of documentation. | |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,24 +1,17 @@ | ||
## Dokka custom format example | ||
|
||
This example demonstrates a few things: | ||
This example demonstrates how to override `.css` styles and add custom images as assets, allowing | ||
you to change the logo used in the header. | ||
|
||
1. How to override css styles and add custom images. | ||
2. How to change logo used in the header. | ||
3. How to register a custom `Dokka` task with its own independent configuration. | ||
You can see up-to-date documentation generated for this example on | ||
[GitHub Pages](https://kotlin.github.io/dokka/examples/dokka-customFormat-example/html/index.html). | ||
|
||
### Running | ||
![screenshot demonstration of output](demo.png) | ||
|
||
`dokkaCustomFormat` task has been created in the buildscript of this example project with a few configuration changes. | ||
### Running | ||
|
||
In order to see the full effect of these changes, run `dokkaCustomFormat` task from your IDE or execute | ||
the following command: | ||
Run `dokkaHtml` task to generate documentation with the custom logo in place: | ||
|
||
```bash | ||
./gradlew clean dokkaCustomFormat | ||
./gradlew dokkaHtml | ||
``` | ||
|
||
--- | ||
|
||
If you run any other `Dokka` task, such as `dokkaHtml`, you'll see vanilla `Dokka` without any alterations. | ||
This is because changes to configuration are applied only within `dokkaCustomFormat` task. This can be useful | ||
if you want to generate multiple versions of documentation with different configuration settings. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,22 @@ | ||
# Dokka Gradle example | ||
|
||
This example demonstrates how to apply Dokka in a simple single-project Gradle build, as well as how to configure it. | ||
|
||
Configuration changes: | ||
|
||
* Custom project name used in the header, `Dokka Gradle Example`. | ||
* Description for the project and the packages taken from [Module.md](Module.md). | ||
* Documentation contains source links that lead to declarations in this GitHub repository. | ||
|
||
You can see up-to-date documentation generated for this example on | ||
[GitHub Pages](https://kotlin.github.io/dokka/examples/dokka-gradle-example/html/index.html). | ||
|
||
![screenshot demonstration of output](demo.png) | ||
|
||
### Running | ||
|
||
Run `dokkaHtml` task to generate documentation for this example: | ||
|
||
```bash | ||
./gradlew dokkaHtml | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,19 @@ | ||
# Dokka Kotlin-as-Java plugin example | ||
|
||
This example demonstrates how you can apply a Dokka plugin in a simple Gradle project. | ||
|
||
In particular, it applies [Kotlin as Java](../../../plugins/kotlin-as-java) Dokka plugin that renders all | ||
Kotlin signatures as Java signatures. | ||
|
||
You can see up-to-date documentation generated for this example on | ||
[GitHub Pages](https://kotlin.github.io/dokka/examples/dokka-kotlinAsJava-example/html/index.html). | ||
|
||
![screenshot demonstration of output](demo.png) | ||
|
||
### Running | ||
|
||
Run `dokkaHtml` task to generate documentation for this example: | ||
|
||
```bash | ||
./gradlew dokkaHtml | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
41 changes: 41 additions & 0 deletions
41
examples/gradle/dokka-library-publishing-example/README.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,41 @@ | ||
# Dokka Library publishing example | ||
|
||
This example demonstrates how you can integrate Dokka into the publishing process of your library, adding | ||
documentation generated by Dokka as artifacts. | ||
|
||
This is useful because some repositories, like Maven Central, require documentation (`javadoc.jar`) to be published | ||
alongside library artifacts. | ||
|
||
You can also use services like [javadoc.io](https://javadoc.io/) to host of your library's API documentation for free | ||
and without any additional setup - it will take documentation pages straight from the published artifact. It works with | ||
both HTML and Javadoc formats as demonstrated by | ||
[com.trib3's Javadocs](https://javadoc.io/doc/com.trib3/server/latest/index.html). | ||
|
||
## Running | ||
|
||
Run `dokkaHtml` task to generate documentation for this example: | ||
|
||
```bash | ||
./gradlew dokkaHtml | ||
``` | ||
|
||
### Javadoc jar | ||
|
||
Run `dokkaJavadocJar` task to create a jar file that contains documentation generated in Dokka's Javadoc format. | ||
|
||
```Bash | ||
./gradlew dokkaJavadocJar | ||
``` | ||
|
||
After that, you can find the jar under `build/libs/dokka-library-publishing-example-javadoc.jar` | ||
|
||
### HTML jar | ||
|
||
|
||
Run `dokkaHtmlJar` task to create a jar file that contains documentation generated in Dokka's HTML format. | ||
|
||
```Bash | ||
./gradlew dokkaHtmlJar | ||
``` | ||
|
||
After that, you can find the jar under `build/libs/dokka-library-publishing-example-html.jar` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,25 @@ | ||
# Dokka MultiModule example | ||
|
||
This example demonstrates how to apply and configure Dokka in a | ||
[multi-project build](https://docs.gradle.org/current/userguide/multi_project_builds.html). | ||
|
||
You can also learn how to set Dokka's version in [gradle.properties](gradle.properties) using `pluginManagement` | ||
configuration block in [settings.gradle.kts](settings.gradle.kts). | ||
|
||
____ | ||
|
||
You can see up-to-date documentation generated for this example on | ||
[GitHub Pages](https://kotlin.github.io/dokka/examples/dokka-multimodule-example/htmlMultiModule/index.html). | ||
|
||
![screenshot demonstration of output](demo.png) | ||
|
||
### Running | ||
|
||
Run `dokkaHtmlMultiModule` task to generate documentation for this example: | ||
|
||
```bash | ||
./gradlew dokkaHtmlMultiModule | ||
``` | ||
|
||
It will generate complete documentation for the root project and its subprojects, with a common | ||
Table of Contents. |
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,2 @@ | ||
kotlinVersion=1.7.20 | ||
dokkaVersion=1.7.20 |
Oops, something went wrong.