Build and deploy beautiful documentation sites that grow with you

Build and deploy beautiful documentation sites that grow with you

OrchidSourceDoc

The base module for adding code documentation to Orchid with Kodiak

official docs

About

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.

Demo

Usage

Basic Usage

This plugin allows you to set up project documentation with multiple modules, which each contain the following features:

  • Source code pages
  • A module README
  • Multiple source directories for each module

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 plugin

The default permalinks are as follows:

  • Module home pages: - :moduleType/:moduleGroup/:module (ex. /kotlindoc/group-one/module-one, /kotlindoc/module-two)
  • Source code pages: - :moduleType/:moduleGroup/:module/:sourceDocPath (ex. /kotlindoc//group-one/module-one/com/app/mainapplication, /kotlindoc/module-two/com/app/mainapplication)

Archetypes

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 PatternExampleDescription
sourcedoc.pages Both module home and source code pages for all languages
sourcedoc.moduleHomePages Just module home pages for all languages
[moduleType].pageskotlindoc.pagesBoth module home and source code pages for one specific language
[moduleType].moduleHomePageskotlindoc.moduleHomePagesJust module home pages for one specific language
[moduleType].[moduleGroup]pageskotlindoc.moduleOnePagesBoth module home and source code pages for one specific module group of one specific language
[moduleType].[moduleGroup]ModuleHomePageskotlindoc.moduleOneModuleHomePagesJust module home pages for one specific module group of one specific language

Source code pages

Archetype PatternExampleDescription
sourcedoc.pages Both module home and source code pages for all languages
sourcedoc.moduleHomePages Just source code pages for all languages
[moduleType].pageskotlindoc.pagesBoth module home and source code pages for one specific language
[moduleType].sourcePageskotlindoc.sourcePagesJust source code pages for one specific language
[moduleType].[sourceType]Pageskotlindoc.ClassesPagesJust source code pages for one specific language and source element type (ex, classes, packages)
[moduleType].[moduleGroup]pageskotlindoc.moduleOnePagesBoth module home and source code pages for one specific module group of one specific language
[moduleType].[moduleGroup]sourcePageskotlindoc.moduleOneSourcePagesJust source code pages for one specific module group of one specific language
[moduleType].[moduleGroup][sourceType]SourcePageskotlindoc.moduleOneClassesPagesJust source code pages for one specific module group of one specific language and source element type (ex, classes, packages)

Collections

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")