Table of Contents generated with DocToc

• Javadoc2Dash - Build Dash docsets from Javadoc
• Gradle plugin
  • Add the plugin to your project
  • Specify settings
  • Create the docset
    • Example
  • Creating the docset feed
    • Example
• Using the API
  • Add dependencies to your project
  • Use the API
• Using the CLI
  • Download the CLI
    • Running in a cloned repository
    • Running a release zip
  • Creating a docset
    • Examples

Javadoc2Dash - Build Dash docsets from Javadoc

This project is based off of https://github.com/Kapeli/javadocset. This is a Java-based solution so that Dash docsets can be easily created from many environments, not just those that run OS X.

There are three ways to create Dash-compatible docsets from Javadoc using this project:

1. Use the Gradle plugin
2. Use the API
3. Use the CLI

Gradle plugin

Add the plugin to your project

Build script snippet for use in all Gradle versions:

buildscript {
  repositories {
    maven {
      url "https://plugins.gradle.org/m2/"
    }
  }
  dependencies {
    classpath "gradle.plugin.com.megatome.javadoc2dash:j2d-gradle:1.0.7"
  }
}

apply plugin: "com.megatome.javadoc2dash"

Build script snippet for new, incubating, plugin mechanism introduced in Gradle 2.1:

plugins {
  id "com.megatome.javadoc2dash" version "1.0.7"
}

Specify settings

javadoc2dash {
  displayName = "My Cool Project"
}

If no settings are provided, the plugin tries to use sensible defaults.

Some Caveats:

• The iconFile should be a 32x32 PNG file, but the plugin does not verify this.
• You should only need to set the javadocTask property when the task you use to create Javadoc is non-standard. For example, there may be a task called allJavadoc in a multi-module project to create an aggregated Javadoc. In this instance, javadocTask should be set to allJavadoc to ensure that the correct documentation is built before creating the docset.
• This plugin applies the java plugin to the project it's run under. This means that in a multi-module project, a top level task named javadoc cannot be created to aggregate the subprojects' documentation. The java plugin creates a javadoc task, so a different name is required - perhaps allJavadoc.

Create the docset

Create the docset with the javadoc2dash task.

Example

apply plugin: 'java'

sourceCompatibility = 1.5
version = '1.0'

buildscript {
  repositories {
    maven {
      url "https://plugins.gradle.org/m2/"
    }
  }
  dependencies {
    classpath "gradle.plugin.com.megatome.javadoc2dash:j2d-gradle:1.0.7"
  }
}

apply plugin: "com.megatome.javadoc2dash"

javadoc2dash {
  docsetName = "MyProject"
  displayName = "My Awesome Project"
  keyword = "mp"
}

Creating the docset feed

If you want to host your own docsets, you need to create a feed per the Dash instructions.

Creating feeds uses the javadoc2dashfeed task.

javadoc2dashfeed {
  feedLocations = [ "http://someserver.com/feeds", "http://someotherserver.com/feeds" ]
}

If no settings are provided, the plugin tries to use sensible defaults.

Example

apply plugin: 'java'

sourceCompatibility = 1.5
version = '1.0'

buildscript {
  repositories {
    maven {
      url "https://plugins.gradle.org/m2/"
    }
  }
  dependencies {
    classpath "gradle.plugin.com.megatome.javadoc2dash:j2d-gradle:1.0.7"
  }
}

apply plugin: "com.megatome.javadoc2dash"

javadoc2dash {
  docsetName = "MyProject"
  displayName = "My Awesome Project"
  keyword = "mp"
}

javadoc2dashfeed {
  feedName = "myproject"
  feedLocations = [ "http://someserver.com/feeds", "http://someotherserver.com/feeds" ]
}

This will generate a feed directory in the javadoc2dash.outputLocation directory. This directory will contain an XML file describing the feed (named myproject.xml in this case), and a compressed version of the docset (named myproject.tgz in this case).

For this example, the XML file will look like this:

<entry>
  <version>1.0</version>
  <url>http://someserver.com/feeds/myproject.tgz</url>
  <url>http://someotherserver.com/feeds/myproject.tgz</url>
</entry>

The XML file should be copied to a location where it can be shared with Dash users, and the tgz file copied to the locations specified in feedLocations.

Using the API

Add dependencies to your project

For Gradle:

repositories {
  jcenter()
}

dependencies {
  compile "com.megatome.javadoc2dash:javadoc2dash-api:1.0.7"
}

For Maven:

<dependency>
  <groupId>com.megatome.javadoc2dash</groupId>
  <artifactId>javadoc2dash-api</artifactId>
  <version>1.0.7</version>
</dependency>

Use the API

DocsetCreator.Builder builder = new DocsetCreator.Builder(docsetName, javadocLocation);
// Optionally -
builder.displayName("Some Name").keyword("keyword");
DocsetCreator creator = builder.build();

try {
  creator.makeDocset();
} catch (BuilderException e) {
  // Something failed!
}

Using the CLI

Download the CLI

Clone the project or grab the latest release. Running the utility will vary a bit depending on how you retrieve the project.

Running in a cloned repository

Running the CLI directly from a Gradle task is not currently supported. A distribution must be created via gradlew :j2d-cli:distZip to create a zip file containing everything needed to run.

Running a release zip

• Either download a release or create a distribution zip as outlined above.
• Unzip the archive to a desired location.
• Open a terminal or command prompt and navigate to the unzipped directory.
• Navigate to the bin directory and run ./j2d-cli (for *NIX/OSX) or j2d-cli.bat (for Windows environments).
• You should see a usage message.

Creating a docset

Docset creation requires at minimum two options: the name of the docset and the location of the Javadoc files to include in the docset.

./j2d-cli --name Sample --javadoc /some/path/to/apidoc

This will create a docset named Sample in the current directory. Docset creation can be customized with optional arguments:

• --displayName: Will set the name as shown in Dash. This is handy if you create a docset with name SampleProject but display name Sample Project instead.
  • This setting will default to the value of --name if omitted.
• --keyword: Will set the keyword used to search in Dash. You could set the keyword for SampleProject to sp, for example.
  • This setting will default to the value of --name if omitted.
• --icon: Specify an icon to be used for the docset. Should be a 32x32 PNG, but this tool does not verify the file's content.
  • No icon will be used if this is omitted.
• --out: Specify a directory to create the docset in.
  • The docset will be created in the current directory if omitted.

Examples

Bare minimum: j2d-cli --name Sample --javadoc /path/to/apidoc

Full options: j2d-cli --name Sample --javadoc /path/to/apidoc --displayName "Awesome Sample API" --keyword asa --iconFile /path/to/icon.png --out /path/to/output

Abbreviated options. Most command-line options can be abbreviated. j2d-cli -n Sample -j /path/to/apidoc -d "Awesome Sample API" -k asa -i /path/to/icon.png -o /path/to/output