OrchidPluginDocs
Auto-generate your plugin's documentation, plus a handy admin panel to bring your plugins documentation to you.
About
OrchidPluginDocs is the solution to out-of-date documentation. It adds an admin panel to Orchid which automatically documents about available features and their possible options for all plugins included in your build.
The same auto-documentation can be used to produce similar static documentation, for example, for documenting your own Orchid plugin.
Installation
dependencies {
orchidRuntime("io.github.javaeden.orchid:OrchidPluginDocs:0.21.2")
}
<dependency>
<groupId>io.github.javaeden.orchid</groupId>
<artifactId>OrchidPluginDocs</artifactId>
<version>0.21.2</version>
<type>pom</type>
</dependency>
libraryDependencies += "io.github.javaeden.orchid" % "OrchidPluginDocs" % "0.21.2"
@file:DependsOn("io.github.javaeden.orchid:OrchidPluginDocs:0.21.2")
Demo
- Try the starter app and visit
http://localhost:8080/admin
- Read the Amazing Admin Panel tutorial
Usage
Documenting your Orchid Plugin
The Orchid Plugin Docs plugin makes it dead-simple to document much of the information that is easily forgotten and not ket up-to-date when developing plugins. It is common to write a short description of your plugin and how to use it, but over time, the specifics of the names of your options, new classes, etc. are often lost and documentation is not updated to reflect these changes. While it isn't possible to solve this problem across arbitrary codebases, Orchid does know a lot about your plugin, and can automate this for your Orchid plugins.
The simplest way for Orchid to document your plugin is to use the pluginDocs
component and pass it your root package.
It will then look through all the classes in that package and its sub-packages, and render a table of all the Options
on that class, including their types and default values. You may pass multiple packages and they all will be documented
in the same way, if you want to be a bit more prescriptive about the packages to document.
---
layout: frontPage
components:
- type: pluginDocs
tableClass: table
tableLeaderClass: hidden
packageNames:
- com.eden.orchid.plugindocs
---
If your want more control over the exact classes that are used, you may set the specific classes (fully-qualified class
names) to the pluginDocs
component's classNames
property, instead of using packageNames
. Again, you may pass
multiple class names to document them all, and you can combine specific classes with whole packages.
You may also find it useful to include the options table directly in written content, rather than just as a Component.
For these cases, you may use the docs
Tag and pass it the fully-qualified name of a class to document.
Bringing your Plugins' Documentation to You
While the pluginDocs
component and docs
tag are intended for use by plugin and theme developers, the Orchid Plugin
Docs also comes with an admin panel that is useful for anyone running Orchid locally, an admin panel that brings the
options for your currently installed plugins to you in one place. You should still visit your plugins' documentation to
learn how to use them, but for a quick reference on the options and basic usage of your plugins, you can view
http://localhost:8080/admin
to see it all in once place.
In this panel, you can view the important class types currently registered with your Orchid site, all extensible classes' used with your Orchid site, and see basic usage for objects of that type. It also includes a command bar for you to execute Orchid Commands.