OrchidSourceDoc

The base module for adding code documentation to Orchid with Kodiak


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 (note: you need to include the plugins for the languages you wish to document):

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

SourceDocs generate a variety of collections which allow you to precisely query these pages. All collections will have a collectionType of the moduleType, such as kotlindoc or javadoc.

If you are using multiple modules, you will get a collection with a collectionId with the name of that module containing all the source pages. 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 type, such as classes or packages.

For example:

Multi-module config

kotlindoc:
  modules:
    - { name: 'OrchidCore',  sourceDirs: ... } # [collectionType='kotlindoc', collectionId='OrchidCore']
    - { name: 'OrchidPages', sourceDirs: ... } # [collectionType='kotlindoc', collectionId='OrchidPages']

# Creates the following collections:
#  - collectionType: kotlindoc, collectionId: OrchidCore
#  - collectionType: kotlindoc, collectionId: OrchidCore-classes
#  - collectionType: kotlindoc, collectionId: OrchidCore-packages
#  - collectionType: kotlindoc, collectionId: OrchidPages
#  - collectionType: kotlindoc, collectionId: OrchidPages-classes
#  - collectionType: kotlindoc, collectionId: OrchidPages-packages

Single-module config

kotlindoc:
  sourceDirs: # [collectionType='kotlindoc', collectionId='kotlindoc']

# Creates the following collections:
#  - collectionType: kotlindoc, collectionId: kotlindoc
#  - collectionType: kotlindoc, collectionId: kotlindoc-classes
#  - collectionType: kotlindoc, collectionId: kotlindoc-packages

In addition, you will have a modules collection, which contains the READMEs for each module. If you set the moduleGroup for your modules, you will also get a collection for each group, containing the READMEs for each of those tagged modules.

kotlindoc:
  modules:
    - { name: 'OrchidCore',      sourceDirs: ..., moduleGroup: 'plugins' } 
    - { name: 'OrchidPages',     sourceDirs: ..., moduleGroup: 'plugins' } 
    - { name: 'OrchidBsDoc',     sourceDirs: ..., moduleGroup: 'themes'  } 
    - { name: 'OrchidEditorial', sourceDirs: ..., moduleGroup: 'themes'  }

# Creates the following collections:
#  - collectionType: kotlindoc, collectionId: modules
#  - collectionType: kotlindoc, collectionId: modules-plugins
#  - collectionType: kotlindoc, collectionId: modules-themes

There are 3 types of menu items available

Modules

Create a menu item linking to the module home pages. You can optionally filter it by a specific module group. Typically added to the Theme menu so it is added to all pages.

Example

theme:
  menu:
    - type: 'sourcedocModules'
      moduleType: 'kotlindoc'
      moduleGroup: 'pages' # optional

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.

Example

theme:
  menu:
    - type: 'sourcedocPages'
      moduleType: 'kotlindoc'
      moduleName: 'OrchidCore'
      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: 'OrchidCore'
      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: 'OrchidCore'
      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), and can optionally include all that items for each section. It is typically added to a Page's menu item through one of the above Archetypes.

Example

kotlinDoc:
  sourcePages:
    menu: 
      - type: 'sourcedocPageLinks'

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'
        moduleType: 'kotlindoc'
        moduleName: 'OrchidCore'
        itemTitleType: 'signature'
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")