Merge pull request #293 from rundeck/enh/ext-docs

Update docs, add docs for extensions

README.md

@@ -19,6 +19,13 @@ This project is now at 1.0.x status.
 * [SSL Configuration](https://rundeck.github.io/rundeck-cli/configuration/ssl/)
 * [Commands](https://rundeck.github.io/rundeck-cli/commands)
 * [Scripting](https://rundeck.github.io/rundeck-cli/scripting)
+* [Java API Library](https://rundeck.github.io/rundeck-cli/javalib/)
+* [Extensions](https://rundeck.github.io/rundeck-cli/extensions/)
+
+# Javadoc
+
+* [rd-api-client ![javadoc](https://javadoc.io/badge2/org.rundeck.api/rd-api-client/javadoc.svg)](https://javadoc.io/doc/org.rundeck.api/rd-api-client)
+* [rd-cli-lib ![javadoc](https://javadoc.io/badge2/org.rundeck.cli/rd-cli-lib/javadoc.svg)](https://javadoc.io/doc/org.rundeck.cli/rd-cli-lib)
 
 # Downloads
 

docs/extensions.md

@@ -0,0 +1,105 @@
+---
+layout: page
+title: Extensions
+permalink: /extensions/
+---
+
+RD can use *extension jars* to add additional functionality.
+
+## Using Extensions
+
+Download an extension jar, and place it in the `RD_EXT_DIR` directory.
+
+By default for UNIX this is located at `~/.rd/ext`, you can overridde the location in your `~/.rd/rd.conf` file by adding:
+
+``` sh
+export RD_EXT_DIR=/my/ext/dir
+```
+
+When you run `rd`, the extensions will be loaded and added as commands in the hierarchy of available subcommands.
+
+You can check the list of loaded extensions by running `rd` with `RD_DEBUG=1`.
+
+## Develop an Extension
+
+Extensions can be developed as Java libraries.
+
+
+### Dependencies
+
+Add the `rd-cli-lib` dependency to your project.
+
+Available in Jcenter repo or [Bintray](https://bintray.com/rundeck/maven/rd-cli-lib).
+
+Javadoc:
+
+* [rd-cli-lib ![javadoc](https://javadoc.io/badge2/org.rundeck.cli/rd-cli-lib/javadoc.svg)](https://javadoc.io/doc/org.rundeck.cli/rd-cli-lib)
+* [cli-toolbelt ![cli-toolbelt](https://javadoc.io/badge2/org.rundeck.cli-toolbelt/toolbelt/javadoc.svg)](https://javadoc.io/doc/org.rundeck.cli-toolbelt/toolbelt)
+
+
+### Gradle example
+
+A demo project can be seen here: <https://github.com/gschueler/rd-extension-demo>
+
+~~~{groovy}
+//use bintray maven repo
+repositories { 
+    //available in jcenter
+    jcenter()
+    //or directly from bintray 
+    maven { 
+        url "https://rundeck.bintray.com/maven" 
+    }
+}
+
+dependencies {
+    api "org.rundeck.cli:rd-cli-lib:{{site.app_version}}"
+    api "org.rundeck.cli-toolbelt:toolbelt-jewelcli:0.2.11"
+    implementation "org.rundeck.api:rd-api-client:{{site.app_version}}"
+
+    implementation 'com.squareup.retrofit2:retrofit:2.7.1'
+    implementation 'com.squareup.retrofit2:converter-jackson:2.7.1'
+    implementation 'com.squareup.retrofit2:converter-simplexml:2.7.1'
+
+}
+~~~
+
+## Implement `RdCommandExtension`
+
+The following example adds the command `rd sub path somecomand`.
+
+```java
+package com.mycompany;
+import org.rundeck.client.tool.extension.RdCommandExtension;
+import org.rundeck.client.tool.extension.RdTool;
+import org.rundeck.client.util.Client;
+import org.rundeck.client.util.ServiceClient;
+import org.rundeck.toolbelt.Command;
+import org.rundeck.toolbelt.CommandOutput;
+import org.rundeck.toolbelt.SubCommand;
+
+@SubCommand(path={"sub","path"})
+class MyClass implements RdCommandExtension{
+    RdTool rdTool;
+    public void setRdTool(RdTool rdTool){
+        this.rdTool=rdTool;
+    }   
+
+    @Command
+    public boolean someCommand(CommandOutput out){
+        out.output("running someCommand");
+    }
+}
+```
+
+Argument parsing is done with the CLI Toolbelt, and can use the JewelCLI library.  See the Example code.
+
+## Declare the Service
+
+The `rd` tool uses the Java ServiceLoader to load extensions on the classpath.
+
+Declare your class in a file called `META-INF/services/org.rundeck.client.tool.extension.RdCommandExtension`
+
+    com.mycompany.MyClass
+
+For a standard Gradle java library, create the file in `src/main/resources/META-INF/services/org.rundeck.client.tool.extension.RdCommandExtension`

docs/javalib.md

@@ -10,17 +10,23 @@ The Java library used by RD can be used as a dependency in your Java project to
 
 Currently the library is published to Bintray (jcenter/maven central TBD).
 
-See: <https://bintray.com/rundeck/rundeck-maven/rd-api-client>
+See: <https://bintray.com/rundeck/maven/rd-api-client>
+
+Javadoc:
+* [rd-api-client ![javadoc](https://javadoc.io/badge2/org.rundeck.api/rd-api-client/javadoc.svg)](https://javadoc.io/doc/org.rundeck.api/rd-api-client)
 
 ## Gradle usage
 
 A demo project can be seen here: <https://github.com/gschueler/rd-api-demo>
 
 ~~~{groovy}
 //use bintray maven repo
-repositories { 
+repositories {
+    //available in jcenter
+    jcenter()
+    //or directly from bintray 
     maven { 
-        url "https://rundeck.bintray.com/rundeck-maven" 
+        url "https://rundeck.bintray.com/maven" 
     }
 }
 
@@ -29,6 +35,3 @@ dependencies {
 }
 ~~~
 
-## Javadoc
-
-(to be published)

rd-cli-tool/src/main/resources/rd-banner.txt

@@ -1,17 +1,9 @@
 
 - ${red}RD$$ - Rundeck API Client Tool (v1.2.2) - ${cyan}https://rundeck.github.io/rundeck-cli/$$
-
 ${red}
-    .:'/*/'`:,·:~·–:.,              ,._., ._
-   /::/:/:::/:::;::::::/`':.,'       /::::::::::'/:/:~-.,
- /·*'`·´¯'`^·-~·:–-'::;:::'`;     /:-·:;:-·~·';/:::::::::`·-.
- '\                       '`;::'i‘   ';           '`~-:;:::::::::'`,
-   '`;        ,– .,        'i:'/     ',.                 '`·-:;:::::'i'‘
-     i       i':/:::';       ;/'        `'i      ,_            '`;:::'¦‘
-     i       i/:·'´       ,:''           'i      ;::/`:,          i'::/
-     '; '    ,:,     ~;'´:::'`:,       _;     ;:/;;;;:';        ¦'/
-     'i      i:/\       `;::::/:'`;'   /::';   ,':/::::::;'       ,´
-      ;     ;/   \       '`:/::::/',/-:;_i  ,'/::::;·´        ,'´
-      ';   ,'       \         '`;/' '`·.     `'¯¯     '   , ·'´
-       `'*´          '`~·-·^'´        `' ~·- .,. -·~ ´
-                                           '$$
+    ________________
+    ___  __ \__  __ \
+    __  /_/ /_  / / /
+    _  _, _/_  /_/ /
+    /_/ |_| /_____/
+$$