OrchidSourceDoc

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:

• Java
• Kotlin
• Groovy
• Swift

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

• Try the example app
• Run SourcedocTest for demo
• View Orchid's own source docs

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

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

Source code pages

Collections

Menu Items