The OrchidKotlindoc plugin integrates with the Dokka tool to embed class and package
info from Kotlin and Java source code directly in your Orchid site. Comment text is compiled as Markdown, and is also
fully-searchable with the OrchidSearch plugin.
Once the Kotlindoc plugin is added to your build, you need to tell Orchid where it can find your Kotlin/Java code. This
is set in your
config.yml as a list of file paths to the root package for your code.
A typical use-case is to have Orchid be in a separate Gradle subproject than the code it's documenting. For example,
app subprojects with the following standard Gradle/Maven project structure:
. / (repo root)
| └── src/main/kotlin/ <-- this is the directory you need to reference
| └── com/example/
| └── main.kt
└── src/orchid/resources/ <-- these are your Orchid resources
config.yml can specify a relative path from your Orchid resources to your Kotlin code source root:
sourceDirs will include them all in the generated documentation, such as including both
java directories for a single module.
Dokka needs the classpath of your source code in order to document everything properly. Specifically, parameters with a
type not in your sources and not part of the Kotlin stdlib will be displayed as
<ERROR CLASS> without the full
You can set the classpath to be used by the Dokka instance running internally with the
--kotlindocClasspath CLI flag.
The following snippet can be used to pass the classpath from Gradle to Orchid/Dokka:
// use Gradle APIs to get the classpath to pass-through to Dokka
args += ["--kotlindocClasspath", project(":app").sourceSets.main.runtimeClasspath.getAsPath()]
See issue #222 for more context on why this is necessary.
OrchidKotlindoc ships with several menu item types that are useful for creating docs with a similar feel to standard
Kotlindoc sites. The
kotlindocPackages simply link to all generated class and package pages,
like the sidebar frames on typical Kotlindoc pages.
kotlindocClassLinks creates links to each individual field, constructor, and method documented in a class page,
similar to the "summary" section of typical Kotlindoc pages. It can only be added to Kotlindoc class pages.
All three of these menu items are best added to the Kotlindoc page Archetypes in
classPages: # <-- applied only to Kotlindoc class pages
- type: "kotlindocClassLinks"
pages: # <-- applied to Kotlindoc class and package pages
- type: "kotlindocClasses"
- type: "kotlindocPackages"