OrchidKotlindoc

Embed Kotlin and Java documentation in your Orchid site using Dokka.


About

The OrchidKotlindoc plugin integrates with the Dokka CLI to embed class and package info and KDoc comments from Kotlin and Java source code directly in your Orchid site.

The suite of Orchid Sourcedocs plugins are for designed for merging source code documentation with the rest of your project site.

Orchid Sourcedocs supports multi-module projects with READMEs and separate doc groups for each module, customizable permalinks, auto-updating menu items, and an ever-improving data model to link to doc pages and display the relationships among different elements.

It also integrates client-side full-text search from the OrchidSearch plugin and is set up for easy page querying or archive generation with the OrchidTaxonomies plugin.

The following languages are currently supported:

Support for the legacy kotlindoc plugin will be removed in version 0.22.0. Until version 0.21.0, legacy kotlindocs were the default, but now they are end-of-life and must be enabled with the --legacySourceDoc CLI flag.

Installation

dependencies {
    orchidRuntime("io.github.javaeden.orchid:OrchidKotlindoc:0.21.2")
}
<dependency>
    <groupId>io.github.javaeden.orchid</groupId>
    <artifactId>OrchidKotlindoc</artifactId>
    <version>0.21.2</version>
    <type>pom</type>
</dependency>
libraryDependencies += "io.github.javaeden.orchid" % "OrchidKotlindoc" % "0.21.2"
@file:DependsOn("io.github.javaeden.orchid:OrchidKotlindoc:0.21.2")

Demo

Single-Module Usage

Configuration

An example of single-module configuration is below. Most properties are optional.

kotlindoc:
  name: 'Project Name'
  sourceDirs: ['../module-one/src/main/kotlin', '../module-one/src/main/java']
  homePagePermalink: '...'
  sourcePagePermalink: '...'
  showRunnerLogs: false
  homePageOnly: false
  args: ['-packageOptions', 'com.example.hidden,+suppress;com.example.alsohidden,+suppress']
DescriptionOptionDefault Value
The name of the module, which becomes the title of the module Homepage.namefalse
Relative paths to directories containing Kotlin or Java source code.sourceDirs[]
Customize the URL path for the homepage.homePagePermalinksee below
Customize the URL path for class and package pages.sourcePagePermalinksee below
Whether to print logs from the underlying Dokka CLIshowRunnerLogsfalse
If true, do not run Dokka. Create docs a module with only a homepage.homePageOnlyfalse
Additional args to pass-through to the Dokka CLI.args[]

Permalinks can be customized for all pages generated by this plugin. For each module, you can set homePagePermalink or sourcePagePermalink with your desired permalink string. The following dynamic path segments are available for these pages (in addition to the standard permalink keys):

  • :moduleType - The "type" of source code you're documenting (kotlindoc)
  • :moduleGroup - Not used for single-module docs
  • :module - Not used for single-module docs
  • :sourceDocPath - The path for each source code doc page, as defined by the Kotlindoc plugin

The default permalinks are as follows:

DescriptionPermalink patternExample
Module home pages:moduleType/:moduleGroup/:module/kotlindoc
Source code pages:moduleType/:moduleGroup/:module/:sourceDocPath/kotlindoc/com/app/mainapplication

Page Archetypes

The pages generated have several archetype keys available, for applying options to these pages in varying levels of granularity:

DescriptionArchetype Pattern
Both module home and source code pages for all languagessourcedoc.pages
Just module home pages for all languagessourcedoc.moduleHomePages
Just source code pages for all languagessourcedoc.sourcePages
Kotlin module home and source code pageskotlindoc.pages
Just Kotlin module home pageskotlindoc.moduleHomePages
Just Kotlin source code pageskotlindoc.sourcePages
Just Kotlin Class source code pageskotlindoc.classesPages
Just Kotlin Package source code pageskotlindoc.packagesPages

Collections

SourceDocs generate a variety of collections which allow you to precisely query these pages. All collections will have a collectionType of the moduleType (kotlindoc).

For a single module, you will get a collection with collectionId of the moduleType. For each of these collections, it will also contain related collections containing the source pages of a specific page types, classes and packages. In addition, you will have a modules collection, which contains the READMEs for each module.

DescriptionCollection TypeCollection ID
All Kotlindoc pageskotlindockotlindoc
All Kotlindoc class pageskotlindockotlindoc-classes
All Kotlindoc package pageskotlindockotlindoc-packages
The Kotlindoc README pagekotlindockotlindoc-modules

There are 3 types of menu items available

Modules

Create a menu item linking to the module home pages. Typically added to the Theme menu so it is added to all pages.

theme:
  menu:
    - type: 'sourcedocModules'
      moduleType: 'kotlindoc'

Pages

Create a menu item linking to all the source pages for a single module. You can optionally filter it by page type, or include all source pages for that module. Typically added to the Theme menu so it is added to all pages.

theme:
  menu:
    - type: 'sourcedocPages'
      moduleType: 'kotlindoc'
      node: 'classes' # optional

By default, all menu items will display the title of the linked page, which is typically a human-readable version of the documented element. You can set itemTitleType: 'ID' to have it display the actual page element ID.

theme:
  menu:
    - type: 'sourcedocPages'
      moduleType: 'kotlindoc'
      node: 'classes'
      itemTitleType: 'ID'

In addition, you can provide an inline Pebble template to render/transform the menu item title however you need. You have access to the original title, the target page, and the element within that template.

theme:
  menu:
    - type: 'sourcedocPages'
      moduleType: 'kotlindoc'
      node: 'classes'
      itemTitleType: 'ID'
      transform: '{{ title|replace({"com.eden.orchid": "c.e.o"}) }}'

Page Links adds menu item links to a single SourceDoc Page. It links to each "section" on that page (such as methods, constructors, or fields on a classes page). Setting includeItems: true will optionally include all that items for each section. It is typically added to a Page's menu item through one of the above Archetypes.

Just like sourcedocPages, you can customize how the menu item text is rendered with itemTitleType. It can be NAME for the element's human-readable name, ID for the actual element ID, or signature to display the fully-formatted element signature.

kotlindoc:
  sourcePages:
    menu:
      - type: 'sourcedocPageLinks'
        itemTitleType: 'signature' # optional, one of [NAME, ID, SIGNATURE]
        includeItems: true # optional

Filtering Docs

Orchid Kotlindoc uses Dokka to convert source code into documentation, so docs are filtered using the methods available to Dokka: extra CLI args to configure per package, and @suppress comments in the code to ignore specific elements.

Dokka Extra CLI Args

Orchid runs Dokka from its CLI, and additional args can be passed to it for extra configuration. Most commonly, this is used for adding -packageOptions arguments to customizing which packages are documented, and the visibility level of the elements in that package. You can also pass any of Dokka's CLI args. They are passed as a freeform list of CLI args to the args property of the module configuration.

kotlindoc:
  name: 'Project Name' 
  sourceDirs: ['../module-one/src/main/kotlin', '../module-one/src/main/java']
  args:
    - '-packageOptions'
    - 'com.example.hidden,+suppress;com.example.alsohidden,+suppress'

The format of these args is: ['-packageOptions', '{semicolon-separated list of package options}'], where:

  • {semicolon-separated list of package options}: {package prefix},{comma-separated list of options}
  • {package prefix}: specifies that a package and all of its subpackages will be configured
  • {comma-separated list of options}: are listed below:
DescriptionCLI valueDefault
Include private and internal members+privateApi
Exclude private and internal members-privateApi
Log warnings for elements with missing KDoc comments+warnUndocumented
Do not log warnings for elements with missing KDoc comments-warnUndocumented
Include elements annotated with @Deprecated+deprecated
Do not include elements annotated with @Deprecated-deprecated
Skip this package entirely+suppress
Include this package-suppress

Dokka @suppress Comments

In addition to customizing the packageOptions through CLI args, you can add @suppress to any individual classes, constructors, properties, or functions to keep them out of the generated docs.

Suppress Classes
/**
 * @suppress
 */
class SuppressedKotlinClass

class VisibleKotlinClass
Suppress Constructors
class KotlinClass(val s1: String) {
    /**
     * @suppress
     */
    constructor() : this("")
}
Suppress Properties
class KotlinClass() {
    /**
     * @suppress
     */
    val suppressedProperty: String
    
    val visibleProperty: String

}
Suppress Functions
/**
 * @suppress
 */
fun suppressedTopLevelFunction: String = ""

fun visibleTopLevelFunction: String = ""

class KotlinClass() {
    /**
     * @suppress
     */
    fun suppressedFunction: String = ""
    
    fun visibleFunction: String = ""
}

Multi-Module Usage

Configuration

An example of multi-module configuration is below. Most properties are optional.

kotlindoc:
  modules:
    - name: 'project-1-name'
      slug: 'project-1'
      moduleGroup: 'group-a'
      sourceDirs: ['../module-one/src/main/kotlin', '../module-one/src/main/java']
      homePagePermalink: '...'
      sourcePagePermalink: '...'
      showRunnerLogs: false
      homePageOnly: false
      relatedModules: ['project-2-name']
      args: ['-packageOptions', 'com.example.hidden,+suppress;com.example.alsohidden,+suppress']
    - name: 'project-2-name'
      ...
DescriptionOptionDefault Value
The name of the module, which becomes the title of the module Homepage.namefalse
The slug prepended to page URLs from this module.slug``
Group multiple modules together for easier configuration and improved site hierarchy.moduleGroup[]
Relative paths to directories containing Kotlin or Java source code.sourceDirs[]
Customize the URL path for the homepage.homePagePermalinksee below
Customize the URL path for class and package pages.sourcePagePermalinksee below
Whether to print logs from the underlying Dokka CLIshowRunnerLogsfalse
If true, do not run Dokka. Create docs a module with only a homepage.homePageOnlyfalse
A list of other modules which contain sources that may be linked to by the pages in this modulerelatedModules[]
Additional args to pass-through to the Dokka CLI.args[]

Permalinks can be customized for all pages generated by this plugin. For each module, you can set homePagePermalink or sourcePagePermalink with your desired permalink string. The following dynamic path segments are available for these pages (in addition to the standard permalink keys):

  • :moduleType - The "type" of source code you're documenting (kotlindoc)
  • :moduleGroup - The module group at declared in the module configuration
  • :module - The name of this specific module
  • :sourceDocPath - The path for each source code doc page, as defined by the Kotlindoc plugin

The default permalinks are as follows:

DescriptionPermalink patternExample without module groupExample with module group
Module home pages:moduleType/:moduleGroup/:module/kotlindoc/project-1/kotlindoc/group-a/project-1
Source code pages:moduleType/:moduleGroup/:module/:sourceDocPath/kotlindoc/project-1/com/app/mainapplication/kotlindoc/group-a/project-1/com/app/mainapplication

Page Archetypes

The pages generated have several archetype keys available, for applying options to these pages in varying levels of granularity:

DescriptionArchetype Pattern
Both module home and source code pages for all languagessourcedoc.pages
Just module home pages for all languagessourcedoc.moduleHomePages
Just source code pages for all languagessourcedoc.sourcePages
Kotlin module home and source code pages for all moduleskotlindoc.pages
Just Kotlin module home pages for all moduleskotlindoc.moduleHomePages
Just Kotlin source code pages for all moduleskotlindoc.sourcePages
Just Kotlin Class source code pages for all moduleskotlindoc.classesPages
Just Kotlin Package source code pages for all moduleskotlindoc.packagesPages
Kotlin module home and source code pages for a single module groupkotlindoc.[module group]Pages
Just Kotlin module home pages for a single module groupkotlindoc.[module group]ModuleHomePages
Just Kotlin source code pages for a single module groupkotlindoc.[module group]SourcePages
Just Kotlin Class source code pages for a single module groupkotlindoc.[module group]ClassesPages
Just Kotlin Package source code pages for a single module groupkotlindoc.[module group]PackagesPages

Collections

SourceDocs generate a variety of collections which allow you to precisely query these pages. All collections will have a collectionType of the moduleType (kotlindoc).

For multiple modules, you will get a collection for each module with collectionId of its name. For each of these collections, it will also contain related collections containing the source pages of a specific page types, classes and packages. In addition, you will have a single modules collection which contains the READMEs of all modules.

DescriptionCollection TypeCollection ID
All Kotlindoc pageskotlindoc[module name]
All Kotlindoc class pageskotlindoc[module name]-classes
All Kotlindoc package pageskotlindoc[module name]-packages
The Kotlindoc README pagekotlindockotlindoc-modules

There are 3 types of menu items available

Modules

Create a menu item linking to the module home pages, optionally filtered by module group. Typically added to the Theme menu so it is added to all pages.

theme:
  menu:
    - type: 'sourcedocModules'
      moduleType: 'kotlindoc'
      moduleGroup: 'group-a' 

Pages

Create a menu item linking to all the source pages for a single module. You can optionally filter it by page type, or include all source pages for that module. Typically added to the Theme menu so it is added to all pages.

theme:
  menu:
    - type: 'sourcedocPages'
      moduleType: 'kotlindoc'
      moduleName: 'project-1-name'
      node: 'classes' # optional

By default, all menu items will display the title of the linked page, which is typically a human-readable version of the documented element. You can set itemTitleType: 'ID' to have it display the actual page element ID.

theme:
  menu:
    - type: 'sourcedocPages'
      moduleType: 'kotlindoc'
      moduleName: 'project-1-name'
      node: 'classes'
      itemTitleType: 'ID'

In addition, you can provide an inline Pebble template to render/transform the menu item title however you need. You have access to the original title, the target page, and the element within that template.

theme:
  menu:
    - type: 'sourcedocPages'
      moduleType: 'kotlindoc'
      moduleName: 'project-1-name'
      node: 'classes'
      itemTitleType: 'ID'
      transform: '{{ title|replace({"com.eden.orchid": "c.e.o"}) }}'

Page Links adds menu item links to a single SourceDoc Page. It links to each "section" on that page (such as methods, constructors, or fields on a classes page). Setting includeItems: true will optionally include all that items for each section. It is typically added to a Page's menu item through one of the above Archetypes.

Just like sourcedocPages, you can customize how the menu item text is rendered with itemTitleType. It can be NAME for the element's human-readable name, ID for the actual element ID, or signature to display the fully-formatted element signature.

kotlindoc:
  sourcePages:
    menu:
      - type: 'sourcedocPageLinks'
        itemTitleType: 'signature' # optional, one of [NAME, ID, SIGNATURE]
        includeItems: true # optional

Filtering Docs

Orchid Kotlindoc uses Dokka to convert source code into documentation, so docs are filtered using the methods available to Dokka: extra CLI args to configure per package, and @suppress comments in the code to ignore specific elements.

Dokka Extra CLI Args

Orchid runs Dokka from its CLI, and additional args can be passed to it for extra configuration. Most commonly, this is used for adding -packageOptions arguments to customizing which packages are documented, and the visibility level of the elements in that package. You can also pass any of Dokka's CLI args. They are passed as a freeform list of CLI args to the args property of the module configuration.

kotlindoc:
  modules:
    - name: 'project-1-name' 
      sourceDirs: ['../module-one/src/main/kotlin', '../module-one/src/main/java']
      args:
        - '-packageOptions'
        - 'com.example.hidden,+suppress;com.example.alsohidden,+suppress'

The format of these args is: ['-packageOptions', '{semicolon-separated list of package options}'], where:

  • {semicolon-separated list of package options}: {package prefix},{comma-separated list of options}
  • {package prefix}: specifies that a package and all of its subpackages will be configured
  • {comma-separated list of options}: are listed below:
DescriptionCLI valueDefault
Include private and internal members+privateApi
Exclude private and internal members-privateApi
Log warnings for elements with missing KDoc comments+warnUndocumented
Do not log warnings for elements with missing KDoc comments-warnUndocumented
Include elements annotated with @Deprecated+deprecated
Do not include elements annotated with @Deprecated-deprecated
Skip this package entirely+suppress
Include this package-suppress

Dokka @suppress Comments

In addition to customizing the packageOptions through CLI args, you can add @suppress to any individual classes, constructors, properties, or functions to keep them out of the generated docs.

Suppress Classes
/**
 * @suppress
 */
class SuppressedKotlinClass

class VisibleKotlinClass
Suppress Constructors
class KotlinClass(val s1: String) {
    /**
     * @suppress
     */
    constructor() : this("")
}
Suppress Properties
class KotlinClass() {
    /**
     * @suppress
     */
    val suppressedProperty: String
    
    val visibleProperty: String

}
Suppress Functions
/**
 * @suppress
 */
fun suppressedTopLevelFunction: String = ""

fun visibleTopLevelFunction: String = ""

class KotlinClass() {
    /**
     * @suppress
     */
    fun suppressedFunction: String = ""
    
    fun visibleFunction: String = ""
}