The base module for adding code documentation to Orchid with Kodiak
This is the base plugin for documenting source code with Orchid for all supported languages. Orchid supports modular projects, with READMEs and separate doc groups for each module, customizable permalinks, multiple types of menu items, and supports full-text search from the OrchidSearch plugin.
No matter which language you are using, its usage is all identical as it is provided by this base plugin.
The following languages are currently supported:
In addition, modules can optionally be grouped by type to provide better URL organization of your docs, and generate archives for each module group. This plugin is designed to work particular well with the OrchidSearch and OrchidTaxonomies plugins.
This plugin allows you to set up project documentation with multiple modules, which each contain the following features:
Single-Module Setup
kotlindoc:
name: 'Project Name'
sourceDirs: ['../module-one/src/main/kotlin', '../module-one/src/main/java']
Multi-Module Setup
kotlindoc:
modules:
- name: 'Module One'
moduleGroup: 'group-one'
sourceDirs: ['../module-one/src/main/kotlin', '../module-one/src/main/java']
- name: 'Module Two'
sourceDirs: ['../module-two/src/main/kotlin', '../module-two/src/main/java']
** Note: The top-level property should be the generator key for the specific type of code documentation you're using,
such as kotlindoc
, javadoc
, or swiftdoc
. All examples here will use kotlindoc
, but you may need to change that.
** See your Admin Panel for the full set of options available for each module type
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, such as kotlindoc
or javadoc
:module
- The module name as specified in the module configuration:moduleGroup
- The module group as specified in the module configuration, or ignored if not provided:sourceDocPath
- The path for each source code doc page, as defined by the specific pluginThe default permalinks are as follows:
:moduleType/:moduleGroup/:module
(ex. /kotlindoc/group-one/module-one
, /kotlindoc/module-two
):moduleType/:moduleGroup/:module/:sourceDocPath
(ex. /kotlindoc//group-one/module-one/com/app/mainapplication
, /kotlindoc/module-two/com/app/mainapplication
)All modules have the config Archetype from their specific generator. So you can configure the default module or all
modules at once from the generator key in config.yml
:
kotlindoc:
modules:
- ...
- ...
homePageOnly: true # applied to all module configs
The pages generated have several archetype keys available, for applying options to these pages in varying levels of granularity:
Module home pages
Archetype Pattern | Example | Description |
---|---|---|
sourcedoc.pages | Both module home and source code pages for all languages | |
sourcedoc.moduleHomePages | Just module home pages for all languages | |
[moduleType].pages | kotlindoc.pages | Both module home and source code pages for one specific language |
[moduleType].moduleHomePages | kotlindoc.moduleHomePages | Just module home pages for one specific language |
[moduleType].[moduleGroup]pages | kotlindoc.moduleOnePages | Both module home and source code pages for one specific module group of one specific language |
[moduleType].[moduleGroup]ModuleHomePages | kotlindoc.moduleOneModuleHomePages | Just module home pages for one specific module group of one specific language |
Source code pages
Archetype Pattern | Example | Description |
---|---|---|
sourcedoc.pages | Both module home and source code pages for all languages | |
sourcedoc.moduleHomePages | Just source code pages for all languages | |
[moduleType].pages | kotlindoc.pages | Both module home and source code pages for one specific language |
[moduleType].sourcePages | kotlindoc.sourcePages | Just source code pages for one specific language |
[moduleType].[sourceType]Pages | kotlindoc.ClassesPages | Just source code pages for one specific language and source element type (ex, classes , packages ) |
[moduleType].[moduleGroup]pages | kotlindoc.moduleOnePages | Both module home and source code pages for one specific module group of one specific language |
[moduleType].[moduleGroup]sourcePages | kotlindoc.moduleOneSourcePages | Just source code pages for one specific module group of one specific language |
[moduleType].[moduleGroup][sourceType]SourcePages | kotlindoc.moduleOneClassesPages | Just source code pages for one specific module group of one specific language and source element type (ex, classes , packages ) |
dependencies {
orchidRuntime("io.github.javaeden.orchid:OrchidSourceDoc:0.18.0")
}
<dependency>
<groupId>io.github.javaeden.orchid</groupId>
<artifactId>OrchidSourceDoc</artifactId>
<version>0.18.0</version>
<type>pom</type>
</dependency>
@file:DependsOn("io.github.javaeden.orchid:OrchidSourceDoc:0.18.0")