SHL-23 - Create docbook based reference guide

docs/src/reference/docbook/index.xml

@@ -16,6 +16,16 @@
                 <surname>Pollack</surname>
                 <affiliation>SpringSource</affiliation>
             </author>
+            <author>
+                <firstname>Jarred</firstname>
+                <surname>Li</surname>
+                <affiliation>VMware</affiliation>
+            </author>
+            <author>
+                <firstname>Costin</firstname>
+                <surname>Leau</surname>
+                <affiliation>SpringSource</affiliation>
+            </author>
         </authorgroup>
 
         <legalnotice>
@@ -32,41 +42,28 @@
     
     <xi:include href="preface.xml"/>
 
-    <!--
     <part id="introduction">
-      <title>Introduction</title>
-       
+      <title>Introduction</title>       
       <xi:include href="introduction/introduction.xml"/>
-      <xi:include href="introduction/why-sdr.xml"/>
       <xi:include href="introduction/requirements.xml"/>
-      <xi:include href="introduction/getting-started.xml"/>
     </part>
 
     <part id="reference">
-      <title>Reference Documentation</title>
-       
+      <title>Reference Documentation</title>       
       <xi:include href="reference/introduction.xml"/>
-      <xi:include href="reference/redis.xml"/>
+      <xi:include href="reference/shell.xml"/>
     </part>
 
-    <part id="appendixes">
-      <title>Appendixes</title>
-      
-      <xi:include href="appendix/introduction.xml"/>
-      <xi:include href="appendix/appendix-schema.xml"/>
+    <part id="dev">
+      <title>Developing Spring Shell Applications</title>
+      <xi:include href="reference/dev-guide/introduction.xml"/>
+      <xi:include href="reference/dev-guide/dev-spring-shell.xml"/>
     </part>
-    <part id="resources">
-      <title>Other Documentation</title>
-       
-      <partintro>
-          <para>
-              In addition to this reference documentation, there are a number of
-              other resources that may help you learn how to use the various key value
-              stores and Spring Data. These additional, third-party resources are
-              enumerated in this section.
-          </para>
-      </partintro>
-      <xi:include href="links.xml"/>       
+
+    <part id="samples">
+      <title>Spring Shell Sample application</title>
+      <xi:include href="samples/introduction.xml"/>
+      <xi:include href="samples/sample-application.xml"/>
     </part>
-    -->
+
 </book>

docs/src/reference/docbook/introduction/introduction.xml

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<partintro version="5.0" xmlns="http://docbook.org/ns/docbook"
+           xmlns:ns5="http://www.w3.org/2000/svg"
+           xmlns:ns4="http://www.w3.org/1999/xhtml"
+           xmlns:ns3="http://www.w3.org/1998/Math/MathML"
+           xmlns:ns2="http://www.w3.org/1999/xlink"
+           xmlns:ns="http://docbook.org/ns/docbook">
+  <para>The Spring Shell provides an interactive shell that lets you
+  contribute commands using a simple POJO based programming model.</para>
+
+  <para>This document is the reference guide for the Spring Shell and covers
+  the key classes that are part of the Shell infrastructure, the plugin model,
+  how to create commands for the shell as well as discussion of the sample
+  application.</para>
+</partintro>

docs/src/reference/docbook/introduction/requirements.xml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter version="5.0" xml:id="requirements"
+         xmlns="http://docbook.org/ns/docbook"
+         xmlns:ns6="http://www.w3.org/1999/xlink"
+         xmlns:ns5="http://www.w3.org/2000/svg"
+         xmlns:ns4="http://www.w3.org/1999/xhtml"
+         xmlns:ns3="http://www.w3.org/1998/Math/MathML"
+         xmlns:ns="http://docbook.org/ns/docbook">
+  <title>Requirements</title>
+
+  <para>The Spring Shell requires JDK level 6.0 (just like Hadoop) and above
+  and the Spring <ulink
+  url="http://www.springsource.org/about">Framework</ulink> 3.0 (3.1
+  recommended) and above.<ulink
+  url="http://www.gemstone.com/products/gemfire"/><ulink
+  url="http://hbase.apache.org/"/><ulink url="http://hive.apache.org/"/><ulink
+  url="http://pig.apache.org/"/></para>
+</chapter>

docs/src/reference/docbook/preface.xml

@@ -1,6 +1,63 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<preface xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="preface">
+<preface version="5.0" xml:id="preface" xmlns="http://docbook.org/ns/docbook"
+         xmlns:ns5="http://www.w3.org/2000/svg"
+         xmlns:ns4="http://www.w3.org/1999/xhtml"
+         xmlns:ns3="http://www.w3.org/1998/Math/MathML"
+         xmlns:ns2="http://www.w3.org/1999/xlink"
+         xmlns:ns="http://docbook.org/ns/docbook">
   <title>Preface</title>
 
-  <para></para>
+  <para>The Spring Shell provides an interactive shell that allows you to
+  plugin your own custom commands using a Spring based POJO programming
+  model.</para>
+
+  <para>The shell has been extracted from the Spring Roo project, giving it a
+  strong foundation and rich feature set. One significant change from Spring
+  Roo is that the plugin model is no longer based on OSGi but instead uses
+  Spring IoC container to discover commands through classpath scanning. There
+  is currently no classloader isolation between plugins, however that maybe
+  added in future versions.</para>
+
+  <para>Spring Shell's features include</para>
+
+  <itemizedlist>
+    <listitem>
+      <para>A POJO based programming model to contribute custom
+      commands</para>
+    </listitem>
+
+    <listitem>
+      <para>Use Spring's classpath scanning functionality as a basis for a
+      command plugin strategy</para>
+    </listitem>
+
+    <listitem>
+      <para>Inheritance of the <link
+      ns2:href="http://static.springsource.org/spring-roo/reference/html-single/index.html#usage-shell">Roo
+      Shell features</link></para>
+    </listitem>
+
+    <listitem>
+      <para>Tab completion</para>
+    </listitem>
+
+    <listitem>
+      <para>Scripting and Script recording</para>
+    </listitem>
+
+    <listitem>
+      <para>Customize command prompt, banner, shell history file name.</para>
+    </listitem>
+  </itemizedlist>
+
+  <para>This document assumes that the reader already has a basic familiarity
+  with the Spring Framework.</para>
+
+  <para>While every effort has been made to ensure that this documentation is
+  comprehensive and there are no errors, nevertheless some topics might
+  require more explanation and some typos might have crept in. If you do spot
+  any mistakes or even more serious errors and you can spare a few cycles
+  during lunch, please do bring the error to the attention of the Spring Shell
+  team by <link ns2:href="https://jira.springsource.org/browse/SHL">raising an
+  issue</link>.</para>
 </preface>

docs/src/reference/docbook/reference/dev-guide/dev-spring-shell.xml

@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter version="5.0" xml:id="dev-shell"
+         xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xmlns:xi="http://www.w3.org/2001/XInclude"
+         xmlns:ns5="http://www.w3.org/1999/xhtml"
+         xmlns:ns4="http://www.w3.org/2000/svg"
+         xmlns:ns3="http://www.w3.org/1998/Math/MathML"
+         xmlns:ns="http://docbook.org/ns/docbook">
+  <title>Developing Spring Shell Applications</title>
+
+  <para>The commands are </para>
+
+  <para/>
+
+  <para/>
+
+  <para/>
+
+  <section>
+    <title>Marker Interface</title>
+
+    <para>The marker interface....</para>
+  </section>
+
+  <section>
+    <title>CLI Annotations</title>
+
+    <para>annotations</para>
+  </section>
+
+  <section>
+    <title>Logging</title>
+
+    <para/>
+  </section>
+
+  <section>
+    <title>Building and running the shell</title>
+
+    <para/>
+  </section>
+</chapter>

docs/src/reference/docbook/reference/dev-guide/introduction.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<partintro>
+  <para>This section provides some guidance on how one can create commands for
+  the Spring Shell.</para>
+</partintro>

docs/src/reference/docbook/reference/introduction.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<partintro>
+  <title>Document structure</title>
+
+  <para>This part of the reference documentation explains the core componets
+  of the Spring Shell.</para>
+</partintro>

docs/src/reference/docbook/reference/shell.xml

@@ -0,0 +1,112 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter version="5.0" xml:id="shell" xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xmlns:xi="http://www.w3.org/2001/XInclude"
+         xmlns:ns5="http://www.w3.org/1999/xhtml"
+         xmlns:ns4="http://www.w3.org/2000/svg"
+         xmlns:ns3="http://www.w3.org/1998/Math/MathML"
+         xmlns:ns="http://docbook.org/ns/docbook">
+  <title>Spring Shell</title>
+
+  <para>The core components of the shell are its plugin model, built-in
+  commands, and converters</para>
+
+  <section>
+    <title>Plugin Model</title>
+
+    <para>The plugin model is based Spring. Each plugin jar is required to
+    contain the file
+    <literal>META-INF/spring/spring-shell-plugin.xml</literal>. These files
+    will be loaded to bootstrap a Spring
+    <interfacename>ApplicationContext</interfacename> when the shell is
+    started. The essential boostrapping code that looks for your contributions
+    looks like this<programlisting>new ClassPathXmlApplicationContext("classpath*:/META-INF/spring/spring-shell-plugin.xml");</programlisting></para>
+
+    <para> In the <literal>spring-shell-plugin.xml</literal> file you should
+    declare the commands and any collaboration objects that support the
+    commands actions. An easy way to declare the commands is to use Spring's
+    component scanning functionality. </para>
+
+    <para>Here is an example <literal>spring-shell-plugin.xml </literal>that
+    from the sample application. </para>
+
+    <programlisting language="xml">&lt;beans xmlns="http://www.springframework.org/schema/beans"
+       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+       xmlns:context="http://www.springframework.org/schema/context"
+       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
+       http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.1.xsd"&gt;
+
+  &lt;context:component-scan base-package="org.springframework.shell.samples.helloworld.commands" /&gt;
+
+&lt;/beans&gt;</programlisting>
+
+    <para>The commands are Spring components, demarcated as such using the
+    <literal>@Component</literal> annotation. For example, the
+    <classname>HelloWorldCommands</classname> class from the sample
+    application looks like this</para>
+
+    <programlisting language="java">@Component
+public class HelloWorldCommands implements CommandMarker {
+
+  // methods with @Cli annotations go here
+
+  // use any Spring annotations for Dependency Injection or other Spring interfaces as required.
+
+}</programlisting>
+
+    <para>One the commands are registered and instantiated by the Spring
+    container, they are registered with the core shell parser so that the
+    <literal>@Cli</literal> annotationscan be processed. The way the commands
+    are identified is through the use of the
+    <interfacename>CommandMarker</interfacename> interface. </para>
+
+    <section>
+      <title>Converters</title>
+
+      <para>The
+      <interfacename>org.springframework.shell.core.Converter</interfacename>
+      interface provides the contract to convert the strings that are entered
+      in the command to rich Java types passed into the arguments of
+      <classname>@Cli</classname>-annotated methods. </para>
+
+      <para>By default converters for common types are registered. These cover
+      primitive types (boolean, int, float...) as well as Date, Character, and
+      File.</para>
+
+      <para>If you need to register any additional
+      <interfacename>Converter</interfacename> instances, register them with
+      the Spring container in the
+      <classname>spring-shell-plugin.xml</classname> file and they will be
+      picked up automatically.</para>
+    </section>
+  </section>
+
+  <section>
+    <title>Built in commands</title>
+
+    <para>There are a few built in commands. Here is a listing of their class
+    name and functionality</para>
+
+    <itemizedlist>
+      <listitem>
+        <para><classname>EssentialCommands</classname> -
+        <literal>exit</literal> and <literal>quit</literal> - to exit the
+        shell.</para>
+      </listitem>
+
+      <listitem>
+        <para><classname>HelpCommands</classname> - <literal>help</literal> -
+        list all commands and their usage</para>
+      </listitem>
+
+      <listitem>
+        <para><classname>OsCommands</classname> - the keyword for this command
+        is the exclamation point, <literal>!</literal>. After the exclamation
+        point you can pass in a unix/windows command string to be
+        executed.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para/>
+  </section>
+</chapter>

docs/src/reference/docbook/samples/introduction.xml

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<partintro>
+  <title>Document structure</title>
+
+  <para>This part of the reference documentation covers the sample
+  applications included with Spring Shell that demonstrate the features in a
+  code centric manner. </para>
+
+  <para><xref linkend="simple-application"/> Describes a simple Spring Shell
+  application that echo's the command parameters to the console</para>
+</partintro>

docs/src/reference/docbook/samples/simple-application.xml

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter version="5.0" xml:id="simple-application" xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xmlns:xi="http://www.w3.org/2001/XInclude"
+         xmlns:ns5="http://www.w3.org/1998/Math/MathML"
+         xmlns:ns4="http://www.w3.org/1999/xhtml"
+         xmlns:ns3="http://www.w3.org/2000/svg"
+         xmlns:ns="http://docbook.org/ns/docbook">
+  <title>Simple sample application using the Spring Shell</title>
+
+  <section id="shell:simple-application">
+    <title>Introduction</title>
+
+    This sample demonstrates how to execute a MapReduce application and a script that interacts with HDFS inside a Spring based application. It does not use spring Batch or Spring Integration.
+
+    <para>The example code is located in the distribution directory
+    <literal>&lt;spring-hadoop-install-dir&gt;/samples/wordcount</literal>.</para>
+  </section>
+</chapter>