OrchidGroovydoc

Let Orchid generate documentation for Groovy or Java sources.


About

The OrchidGroovydoc plugin integrates with the Groovydoc tool to embed class and package info from Groovy and Java source code directly in your Orchid site. Comment text is compiled as Markdown, and is also fully-searchable with the OrchidSearch plugin.

The behavior of the OrchidGroovydoc is changing. Please see the 0.18.0 Migration Guide for more details.

This plugin is being deprecated in favor of a new, more unified, and more modular code-documentation plugin, OrchidSourceDoc. All configuration will be defined by that plugin, and this plugin will simply provide Groovy language support for that plugin.

The new system is currently experimental and is an opt-in feature for 0.18.x Orchid versions. It can be enabled now with the --experimentalSourceDoc CLI flag. The legacy behavior is scheduled for removal in version 0.19.0.

Demo

Usage

The article How to Document a Kotlin Project is the best way to get started using Orchid for code documentation, check it out for a beginning-to-end guide to using Orchid.

While this article is specific to the Kotlin language support in Orchid, working with Groovy in Orchid is almost identical, with the specifics outlined below.

The behavior of the OrchidGroovydoc is changing. Please see the 0.18.0 Migration Guide for more details.

The docs below are for the legacy Groovydoc plugin. For docs on using the new SourceDoc system, visit the OrchidSourceDoc plugin homepage.

Basic Usage

Once the Groovydoc plugin is added to your build, you need to tell Orchid where it can find your Groovy/Java code. This is set in your config.yml as a list of file paths to the root package for your code.

A typical use-case is to have Orchid be in a separate Gradle subproject than the code it's documenting. For example, using docs and app subprojects with the following standard Gradle/Maven project structure:

. / (repo root)
├── app
|   └── src/main/groovy/ <-- this is the directory you need to reference
|       └── com/example/
|           └── Main.groovy
└── docs
    └── src/orchid/resources/ <-- these are your Orchid resources
        ├── homepage.md
        └── config.yml

Your config.yml can specify a relative path from your Orchid resources to your Groovy code source root:

groovydoc:
  sourceDirs:
    - './../../../../app/src/main/groovy'

Setting multiple sourceDirs will include them all in the generated documentation, such as including both groovy and java directories for a single module.

OrchidGroovydoc ships with several menu item types that are useful for creating docs with a similar feel to standard Groovydoc sites. The groovydocClasses and groovydocPackages simply link to all generated class and package pages, like the sidebar frames on typical Groovydoc pages.

groovydocClassLinks creates links to each individual field, constructor, and method documented in a class page, similar to the "summary" section of typical Groovydoc pages. It can only be added to Groovydoc class pages.

All three of these menu items are best added to the Groovydoc page Archetypes in config.yml:

groovydoc:
  classPages: # <-- applied only to Groovydoc class pages
    menu:
      - type: "groovydocClassLinks"
  pages:  # <-- applied to Groovydoc class and package pages
    menu:
      - type: "groovydocClasses"
      - type: "groovydocPackages"
dependencies {
    orchidRuntime("io.github.javaeden.orchid:OrchidGroovydoc:0.18.0")
}
<dependency>
    <groupId>io.github.javaeden.orchid</groupId>
    <artifactId>OrchidGroovydoc</artifactId>
    <version>0.18.0</version>
    <type>pom</type>
</dependency>
@file:DependsOn("io.github.javaeden.orchid:OrchidGroovydoc:0.18.0")