Start to breakup README.md documentation

CONTRIBUTING.md

@@ -0,0 +1,70 @@
+# Contributing to Spring Zero
+Spring Zero is released under the non-restrictive Apache 2.0 license. If you would like
+to contribute something, or simply want to hack on the code this document should help
+you get started.
+
+
+## Working with the code
+If you don't have an IDE preference we would recommend that you use 
+[Spring Tools Suite](http://www.springsource.com/developer/sts) or 
+[Eclipse](http://eclipse.org) when working with the code. We use the 
+[m2eclipe](http://eclipse.org/m2e/) eclipse plugin for maven support. Other IDEs
+and tools should also work without issue.
+
+
+### Building from source
+To build the source you will need to install 
+[Apache Maven](http://maven.apache.org/run-maven/index.html) v3.0 or above. The project
+can be build using the standard maven command:
+
+	$ mvn clean install
+
+If you are rebuilding often, you might also want to skip the tests until you are ready
+to submit a pull request:
+
+	$ mvn clean install -DskipTests
+
+
+### Importing into eclipse with m2eclipse
+We recommend the [m2eclipe](http://eclipse.org/m2e/) eclipse plugin when working with
+eclipse. If you don't already have m2eclipse installed it is available from the "eclipse
+marketplace".
+
+Spring Zero includes project specific source formatting settings, in order to have these
+work with m2eclipse, we provide an additional eclipse plugin that you can install:
+
+* Select `Install new software` from the `help` menu
+* Click `Add...` to add a new repository
+* Click the `Archive...` button
+* Select `org.eclipse.m2e.maveneclipse.site-0.0.1-SNAPSHOT-site.zip`
+  from the `eclipse` folder in this checkout
+* Install "Maven Integration for the maven-eclipse-plugin"
+
+_NOTE: This plugin is optional. Projects can be imported without the plugin, your code 
+changes just won't be automatically formatted._ 
+
+With the requisite eclipse plugins installed you can select 
+`import existing maven projects` from the `file` menu to import the code. You will
+need to import the root `spring-zero` pom and the `spring-zero-samples` pom separately. 
+
+
+### Importing into eclipse without m2eclipse
+If you prefer not to use m2eclipse you can generate eclipse project meta-data using the
+following command:
+
+	$ mvn eclipse:eclipse
+
+The generated eclipse projects can be imported by selecting `import existing projects`
+from the `file` menu.
+
+### Importing into other IDEs
+Maven is well supported by most Java IDEs. Refer to you vendor documentation.
+
+
+### Integration tests
+The sample application are used as integration tests during the build. Due to the
+fact that they make use of the `spring-package-maven-plugin` they cannot be called
+directly, and so instead are launched via the `maven-invoker-plugin`. If you encounter
+build failures running the integration tests, check the `build.log` file in the appropriate
+sample directory.
+ 

README.md

@@ -1,45 +1,57 @@
 # Spring Zero
-
+Spring Zero is "Spring for Snowboarders".  If you are kewl, or just impatient, and you 
-Spring Zero is "Spring for Snowboarders".  If you are kewl, or
+want to use Spring, then this is the place to be. Spring Zero is the code-name for a
-just impatient, and you want to use Spring, then this is the place to
+group of related technologies, that will get you up and running with 
-be. Spring Zero is a toolkit and runtime platform that will get
+Spring-powered,  production-grade applications and services with absolute minimum fuss. 
-you up and running with Spring-powered, production-grade applications
+It takes an opinionated view of the Spring family so that new and existing users can 
-and services with absolute minimum fuss. It takes an opinionated view
+quickly get to the bits they need. Assumes limited knowledge of the Java development 
-of the Spring family so that new and existing users can quickly get to
+ecosystem. Absolutely no code generation and no XML (unless you really want it).
-the bits they need. Assumes no knowledge of the Java development
-ecosystem. Absolutely no code generation and no XML (unless you really
-want it).
 
 The goals are:
+* Radically faster and widely accessible getting started experience for Spring
+  development
+* Be opinionated out of the box, but get out of the way quickly as requirements start to 
+  diverge from the defaults
+* Provide a range of non-functional features that are common to large classes of projects
+  (e.g. embedded servers, security, metrics, health checks, externalized configuration)
+* First class support for REST-ful services, modern web applications, batch jobs, and 
+  enterprise integration
+* Applications that adapt their behavior or configuration to their environment
+* Optionally use Groovy features like DSLs and AST transformations to accelerate the 
+  implementation of basic business requirements
+
 
-* Radically faster and widely accessible getting started experience
-  for Spring development
-* Be opinionated out of the box, but get out of the way quickly as
-  requirements start to diverge from the defaults
-* Provide a range of non-functional features that are common to large
-  classes of projects (e.g. embedded servers, security, metrics,
-  health checks, externalized configuration)
-* First class support for REST-ful services, modern web applications,
-  batch jobs, and enterprise integration
-* Applications that adapt their behaviour or configuration to their
-  environment
-* Optionally use Groovy features like DSLs and AST transformations to
-  accelerate the implementation of basic business requirements
-  
 ## Installing
-You need to build from source for now, but when it's done instructions will look like this:
+You need to [build from source](#building-from-source) for now, but when it's done 
+instructions will look like this:
 
-1) Get Java.  Download and install the Java SDK from www.java.com
+1) Get Java.  Download and install the Java SDK from [www.java.com](http://www.java.com)
 
 2) Get Spring
 
-     $ curl -s spring.cfapps.io/installer | bash
+	$ curl -s spring.cfapps.io/installer | bash
-     
+
-   or use the Windows installer
+   or use the [Windows installer](#installing)
+
+
+## Building from source
+Spring Zero can be [built with maven](http://maven.apache.org/run-maven/index.html) v3.0 
+or above.
+
+	$ mvn clean install
+
+An `alias` can be used for the Spring Zero command line tool:
+
+	$ alias spr="java -jar ~/.m2/repository/org/springframework/zero/spring-cli/0.5.0.BUILD-SNAPSHOT/spring-cli-0.5.0.BUILD-SNAPSHOT.jar"
+
+_Also see [CONTRIBUTING.md](/CONTRIBUTING.md) if you want to submit pull requests._  
 
-3) Get to Work!
 
-    $ cat > app.groovy
+## Quick Start Example
+The Spring Zero command line tool uses Groovy underneath so that we can present simple 
+snippets  that can just run, for example:
+
+	$ cat > app.groovy
 	@Controller
 	class ThisWillActuallyRun {
 		@RequestMapping("/")
@@ -48,30 +60,24 @@ You need to build from source for now, but when it's done instructions will look
 			return "Hello World!"
 		}
 	}
-    $ spring run app.groovy
+	<ctrl-d>
-    $ curl localhost:8080
+	$ spr run app.groovy
-    Hello World!
+	$ curl localhost:8080
-
+	Hello World!
-
-## What? It's Groovy then? or like Grails? or Roo?
 
-There is a command line tool that uses Groovy underneath so that we
-can present simple snippets that can just run just like the slimline
-`app.groovy` example above.  Groovy makes this really easy.
-
-If you don't want to use the command line tool, or you would rather
-work using Java and an IDE you can. Just add a `main()` method that
-calls `SpringApplication` and add `@EnableAutoConfiguration`:
 
+If you don't want to use the command line tool, or you would rather work using Java and 
+an IDE you can. Just add a `main()` method that calls `SpringApplication` and 
+add `@EnableAutoConfiguration`:
 
 	import org.springframework.stereotype.*;
 	import org.springframework.web.bind.annotation.*;
 	import org.springframework.bootstrap.context.annotation.*;
-
+	
 	@Controller
 	@EnableAutoConfiguration
 	public class SampleController {
-
+	
 		@RequestMapping("/")
 		@ResponseBody
 		String home() {
@@ -81,109 +87,101 @@ calls `SpringApplication` and add `@EnableAutoConfiguration`:
 		public static void main(String[] args) throws Exception {
 			SpringApplication.run(SampleController.class, args);
 		}
+	
+	}
+	
+_NOTE: the above example assumes your build system has imported the `spring-starter-web`
+maven pom._
 
-    }
-
-## Spring Zero Themes
 
-There are a number of themes in Zero. Here are the important
+## Spring Zero Components
-ones:
+There are a number of components in Zero. Here are the important ones:
 
 ### The Spring CLI
+The 'spring' command line application compiles and runs Groovy source, making it super 
+easy to write the absolute minimum of code to get an application running. Spring CLI 
+can also watch files, automatically recompiling and restarting when they change.
+
+*See [spring-cli/README.md](spring-cli/README.md).*
 
-The 'spring' command line application compiles and runs Groovy source,
-making it super easy to write the absolute minimum of code to get an
-application running. Spring CLI can also watch files, automatically
-recompiling and restarting when they change.
 
 ### Spring Bootstrap
+The main library providing features that support the other parts of Spring Zero. 
+Features include:
+
+* `SpringApplication` - a class with static convenience methods that make it really easy 
+  to write a standalone Spring Application. Its sole job is to create and refresh an 
+  appropriate Spring `ApplicationContext`.
+* Embedded web applications with a choice of container (Tomcat or Jetty for now)
+* First class externalized configuration support 
 
-The main library providing features that support the other parts of
+_See [spring-bootstrap/README.md](spring-bootstrap/README.md)._
-Spring Zero.  Features include:
 
-* `SpringApplication` - a class with static convenience methods that
-  make it really easy to write a standalone Spring Application. Its
-  sole job is to create and refresh an appropriate Spring
-  `ApplicationContext`.
-* Embedded web applications with a choice of container (Tomcat or
-  Jetty for now)
   
 ### Spring Autoconfigure
+Spring Zero can configure large parts of common applications based on detecting the 
+content of the classpath and any existing application context. A single 
+`@EnableAutoConfigure` annotation triggers auto-configuration of the Spring context. 
 
-Spring Zero can configure large parts of common applications based on
+Auto-configuration attempts to guess what beans a user might want  based on their 
-detecting the content of the classpath and any existing application
+classpath. For example, If a 'HSQLDB' is on the classpath the user probably wants an 
-context:
+in-memory database to be defined. Auto-configuration will back away as the user starts 
-
+to define their own beans.
-* `@EnableAutoConfigure` is an annotation that triggers
-  auto-configuration of the Spring context. Auto-configuration
-  attempts to guess what beans a user might want based on their
-  classpath. For example, If a 'HSQLDB' is on the classpath the user
-  probably wants an in-memory database to be
-  defined. Auto-configuration will back away as the user starts to
-  define their own beans.
-* `@Conditional` is an annotation in Spring 4.0 that allows you to
-  control which parts of an application are used at runtime. Spring
-  Zero provides some concrete implementations of conditional
-  configuration, e.g. `@ConditionalOnBean`,
-  `@ConditionalOnMissingBean` and `@ConditionalOnClass`.
 
-### Spring Actuator
+_See [spring-autoconfigure/README.md](spring-autoconfigure/README.md)._
-
-Spring Actuator uses auto-configuration features to decorate
-your application with features that make it instantly deployable and
-supportable in production.  For instance if you are writing a JSON web
-service then it will provide a server, security, logging, externalized
-configuration, management endpoints, an audit abstraction, and more.
-If you want to switch off the built in features, or extend or replace
-them, it makes that really easy as well.
 
-### Service Wrappers and Deployability
 
-Spring Zero helps you to take that last step from finishing a
+### Spring Actuator
-development iteration to getting the code running in production.
+Spring Actuator uses auto-configuration to decorate your application with features that 
-Without having to think too much about it, other than choosing your
+make it instantly deployable and supportable in production.  For instance if you are 
-deployment environment (CentOS, Ubuntu, Windows etc) you should be
+writing a JSON web service then it will provide a server, security, logging, externalized
-able to stand up an instance, or multiple instances, of your component
+configuration, management endpoints, an audit abstraction, and more. If you want to 
-and have them fit seamlessly into the operating system environment.
+switch off the built in features, or extend or replace them, it makes that really easy as well.
 
-### Spring Starters
+_See [spring-actuator/README.md](spring-actuator/README.md)._
 
-Spring Starters are a set of convenient dependency
-descriptors that you can include in your application.  You get a
-one-stop-shop for all the Spring and related technology that you need
-without having to hunt through sample code and copy paste loads of
-dependency descriptors. For example, if you want to get started using
-Spring and JPA for database access just include one dependency in your
-project, and you are good to go.
 
-## Building the code
+### Spring Starters
-Use maven to build the source code.
+Spring Starters are a set of convenient dependency descriptors that you can include in 
+your application. You get a one-stop-shop for all the Spring and related technology 
+that you need without having to hunt through sample code and copy paste loads of
+dependency descriptors. For example, if you want to get started using Spring and JPA for 
+database access just include one dependency in your project, and you are good to go.
 
-	$ mvn clean install
+_See [spring-starters/README.md](spring-starters/README.md)._
 
-## Importing into eclipse
-You can use m2e or `maven eclipse:eclipse`.
 
-Project specific settings are configured for source formatting. If you
+### Packaging
-are using m2e you can follow these steps to install eclipse support
+The [spring-launcher](spring-launcher/) and 
-for formatting:
+[spring-maven-packaging-plugin](spring-maven-packaging-plugin) provide a convenient way
+to package you application for release. Applications can be released as a single jar
+file that can simply be launched using `java -jar`.
 
-* Select `Install new software` from the `help` menu
+_See [spring-launcher/README.md](spring-launcher/README.md) & 
-* Click `Add...` to add a new repository
+[spring-package-maven-plugin/README.md](spring-package-maven-plugin/README.md)._
-* Click the `Archive...` button
-* Select `org.eclipse.m2e.maveneclipse.site-0.0.1-SNAPSHOT-site.zip`
-  from the `eclipse` folder in this checkout
-* Install "Maven Integration for the maven-eclipse-plugin"
 
-Or if you prefer you can import settings manually from the `/eclipse` folder.
 
 ## Samples
-The following samples are included. To run use `java -jar target/<archive>.jar`
+Groovy samples for use with the command line application are available in
-
+[spring-cli/samples](spring-cli/samples/). To run the CLI samples type 
-* spring-zero-simple-sample - A simple command line application
+`spr run <sample>.groovy` from samples directory.
-* spring-zero-jetty-sample - Embedded Jetty
+
-* spring-zero-tomcat-sample - Embedded Tomcat
+Java samples are available in [spring-zero-sample](spring-zero-samples/) and should
-* spring-zero-service-sample - Simple REST service with production features
+be build with maven and run use `java -jar target/<sample>.jar`. The following java
-* spring-batch-sample - Define and run a Batch job in a few lines of code
+samples are provided:
-* spring-zero-data-sample - Spring Data JPA + Hibernate + HSQLDB
+
+* spring-zero-sample-simple - A simple command line application
+* spring-zero-sample-tomcat - Embedded Tomcat
+* spring-zero-sample-jetty - Embedded Jetty
+* spring-zero-sample-actuator - Simple REST service with production features
+* spring-zero-sample-actuator-ui - A web UI example with production features
+* spring-zero-sample-web-ui - A thymeleaf web application
+* spring-sample-batch - Define and run a Batch job in a few lines of code
+* spring-sample-data-jpa - Spring Data JPA + Hibernate + HSQLDB
+* spring-zero-sample-integration - A spring integration application
+* spring-zero-sample-profile - example showing Spring's `@profile` support
+* spring-zero-sample-traditional - shows Spring Zero with more traditional WAR packaging 
+  (but also executable using `java -jar`)
+* spring-zero-sample-xml - Example show how Spring Zero can be mixed with trditional XML
+  configuration
 

spring-autoconfigure/README.md

@@ -0,0 +1 @@
+# Spring AutoConfigure

spring-bootstrap/README.md

@@ -0,0 +1 @@
+# Spring Bootstrap

spring-cli/README.md

@@ -0,0 +1 @@
+# Spring CLI

spring-launcher/README.md

@@ -0,0 +1 @@
+# Spring Launcher

spring-package-maven-plugin/README.md

@@ -0,0 +1 @@
+# Spring Package Maven Plugin

spring-starters/README.md

@@ -0,0 +1 @@
+# Spring Starters