Plugin Documentation Task

Plugin Documentation Task

Ant task that generates HTML documentation for all JNode plugins, including their dependencies, extensions, and licenses.

Overview

PluginDocumentationTask is an Ant build task under builder/src/builder/org/jnode/build/documentation/ that scans plugin descriptor XML files and produces a navigable HTML documentation site. It is invoked from all/build.xml as part of the build process to generate plugin reference documentation alongside the boot image and ISO artifacts.

The task reads plugin descriptors (plugin.xml), parses plugin metadata, resolves inter-plugin dependencies, and outputs a multi-frame HTML site with:

• An index/overview page
• Per-plugin detail pages (id, name, version, provider, license, runtime libraries, extension points, extensions)
• Package index by Java package name
• License index grouping plugins by license
• Optional dependency tree (via Graphviz dot)

Key Components

Class	Role
PluginDocumentationTask	Main Ant task. Extends AbstractPluginTask. Coordinates scanning, loading, writing.
PluginData	Holds parsed plugin metadata: descriptor, HTML filename, full id_version key.
DotBuilder	Generates Graphviz DOT file and runs dot to produce overview-tree.png.
LicenseEntry	Comparable (name, URL) pair with toHtmlString(). Maps plugin licenses to OS links.
PackageData	Comparable wrapper pairing a Java package name with its plugin.
ToolbarEntry	Navigation toolbar entry (title, href) for the generated HTML pages.

Supporting Infrastructure

Class	Role
AbstractPluginTask	Base class providing getPluginDir(), readDescriptor(File), getDescriptorFiles()
PluginDescriptor	Core plugin model: id, version, name, provider, license, prerequisites, runtime, extensions
PluginPrerequisite	A requires dependency: pluginReference (id), optional version range
Extension / ExtensionPoint	Plugin contribution model
Library	Runtime library with getExports() and getExcludes()
ConfigurationElement	Extension configuration with nested elements and attributes

How It Works

Execution Flow

execute()
  ├── getDescriptorFiles()           // Collect all plugin.xml from descriptorSets
  ├── for each descrFile:
  │   └── loadPluginData()           // readDescriptor → PluginData with fullId
  ├── for each PluginData:
  │   └── writePluginDocumentation() // Per-plugin HTML page
  ├── writeCSS()                     // index.css
  ├── writeAllFrame()                // Left nav: all-frame.html
  ├── writeOverviewSummary()         // Plugin index table
  ├── writeOverviewPackage()         // Packages by plugin
  ├── writeOverviewLicense()         // Plugins by license
  ├── writeOverviewTree()            // Optional: runs DotBuilder → overview-tree.png
  └── writeIndex()                  // frameset index.html

Plugin Data Loading

Plugin descriptors are read via AbstractPluginTask.readDescriptor() and stored in a TreeMap<String, PluginData> keyed by fullId = id_version. Duplicate full IDs cause a BuildException. The HTML filename is set to plugins/<id>.html.

Per-Plugin Documentation

Each plugin page (written by writePluginDocumentation) includes:

1. Plugin summary table: id, name, version, provider, license, plugin class, flags (system/auto-start)
2. Requires: Direct prerequisites with links to their HTML pages
3. Required by: Reverse dependency lookup via getRequiredBy()
4. Libraries: Runtime libraries with exported packages and exclusions
5. Extension points: Declared extension points
6. Extensions: Contributed extensions with full configuration element nesting rendered as HTML

License Handling

findLicense() matches licenseName against KNOWN_LICENSES (BSD, GPL, LGPL, CPL, Classpath, Apache, Apache2.0, Zlib). Unknown licenses default to LicenseEntry.UNKNOWN with no URL. The license index groups all plugins by their resolved LicenseEntry.

Dependency Tree Generation

When setTree(true) is called, DotBuilder writes a Graphviz DOT file listing all plugins as nodes and draws directed edges for each prerequisite. It then spawns dot -Tpng to render overview-tree.png. This requires Graphviz to be installed on the build host.

Ant Integration

The task is configured in all/build.xml with nested <descriptorset> elements pointing to plugin descriptor directories, todir for the output directory, and pluginDir pointing to the plugins source directory.

<taskdef name="pluginDoc" classname="org.jnode.build.documentation.PluginDocumentationTask"/>
<pluginDoc pluginDir="${plugins.src.dir}">
  <descriptorset dir="${plugins.src.dir}">
    <include name="**/plugin.xml"/>
  </descriptorset>
  <descriptorset dir="${core.descriptors.dir}">
    <include name="**/plugin.xml"/>
  </descriptorset>
  <descriptorset dir="${fs.descriptors.dir}">
    <include name="**/plugin.xml"/>
  </descriptorset>
  ...
  <todir value="${build.docs.dir}"/>
</pluginDoc>

Gotchas

• DescriptorSets required: At least one <descriptorset> must be provided or a BuildException is thrown.
• todir and pluginDir required: Both attributes must be set; missing either throws a BuildException.
• Graphviz dependency: The dependency tree feature (setTree(true)) silently fails if dot is not on the PATH — Runtime.exec().waitFor() catches InterruptedException but not a missing executable.
• Duplicate full IDs: A BuildException is thrown if two plugins share the same id_version combination, even across different descriptor files.
• No Javadoc integration: The task generates structural plugin documentation only. Javadoc HTML must be generated separately (e.g., via ant javadoc).
• ConfigurationElement rendering: Nested configuration elements are rendered recursively with &nbs  indentation and <br/> line breaks, producing a flat HTML dump rather than structured markup.
• Unknown licenses: Plugins without a recognized license name appear with "-" and no URL in the license index.

Related Pages

Build-System | Plugin-System | Plugin-Descriptor-Schema | Builder-Packager | Plugin-Dependency-Checker | Boot-CD-ROM-Builder