Prepare better docs structure

build.gradle

@@ -149,7 +149,15 @@ configure(rootProject) {
 
 	dependencies { // for integration tests
 	}
-    
+
+	task copyDocsSamples(type: Copy) {
+		from 'spring-statemachine-core/src/test/java/org/springframework/statemachine/docs'
+		include '*.java'
+		into 'docs/src/reference/asciidoc/samples'
+	}
+
+	asciidoctor.dependsOn copyDocsSamples
+
 	task api(type: Javadoc) {
 		group = 'Documentation'
 		description = 'Generates aggregated Javadoc API documentation.'

docs/src/reference/asciidoc/appendix.adoc

@@ -3,14 +3,99 @@
 
 :numbered!:
 
+[appendix]
+== Support Content
+This appendix provides generic information about used classes and
+material in this reference documentation.
+
+=== Classes Used in This Document
+
+[source,java,indent=0]
+----
+include::samples/MyStates.java[tags=snippetA]
+----
+
+[source,java,indent=0]
+----
+include::samples/MyEvents.java[tags=snippetA]
+----
+
 [appendix]
 == State Machine Concepts
 This appendix provides generic information about state machines.
 
+
+[glossary]
 === Glossary
 
-state machine::
-machine of sort.
+State Machine::
+Main entity driving a collection of states together with regions,
+transitions and events.
+
+State::
+A state models a situation during which some invariant condition
+holds. State is the main entity of a state machine where state changes
+are driven by an events.
+
+Transition::
+A transition is a relationship between a source state and a target
+state. It may be part of a compound transition, which takes the state
+machine from one state configuration to another, representing the complete
+response of the state machine to an occurrence of an event of a
+particular type.
+
+Event::
+An entity which is send to a state machine which then drives a various
+state changes.
+
+Initial State::
+A special state in which the state machine starts. Initial state is
+always bound to a particulal state machine or a region. A state
+machine with a multiple regions may have a multiple initial states.
+
+End State::
+Also called as a final state is a special kind of state signifying
+that  the enclosing region is completed. If the enclosing region is
+directly contained in a state machine and all other regions in the
+state machine also are completed, then it means that the entire state
+machine is completed.
+
+Region::
+A region is an orthogonal part of either a composite state or a state
+machine. It contains states and transitions.
+
+Guard::
+Is a boolean expression evaluated dynamically based on the value of
+extended state variables and event parameters. Guard conditions affect
+the behavior of a state machine by enabling actions or transitions
+only when they evaluate to TRUE and disabling them when they evaluate
+to FALSE.
+
+Action::
+A action is a behaviour executed during the triggering of the
+transition.
+
+=== A State Machines Crash Course
+TBD.
+
+==== States
+TBD.
+
+==== Guard Conditions
+TBD.
+
+==== Events
+TBD.
+
+==== Transitions
+TBD.
+
+==== Actions
+TBD.
+
+==== Hierarchical State Machines
+TBD.
+
+==== Regions
+TBD.
 
-state::
-a stage in a state machine.

docs/src/reference/asciidoc/index.adoc

@@ -32,6 +32,8 @@
 include::preface.adoc[]
 include::introduction.adoc[]
 
-[[springandhadoop]]
+[[springandsm]]
 include::sm.adoc[]
+
+include::sm-examples.adoc[]
 include::appendix.adoc[]

docs/src/reference/asciidoc/introduction.adoc

@@ -2,4 +2,6 @@
 = Introduction
 
 == Requirements
-TBD
+
+Spring Statemachine {revnumber} is built and tested with JDK 7, Spring
+Framework {spring-version}.

docs/src/reference/asciidoc/preface.adoc

@@ -1,4 +1,31 @@
 [preface]
 == Preface
-Spring Statemachine is a framework for application developers to use
+Spring State Machine(SSM) is a framework for application developers to use
 state machine concepts with Spring.
+
+Concept of a state machine is most likely older that any of a reader
+of this reference documentation and definitely older than a Java
+language itself. Description of finite automate dates back to 1943
+when gentlements Warren McCulloch and Walter Pitts wrote a paper about
+it. Later George H. Mealy presented a state machine concept in 1955
+which is known as a Mealy Machine. A year later in 1956 Edward F.
+Moore presented another paper which is known as a Moore Machine. If
+you're ever read anything about state machines, names Mealy and Moore
+should have popped up at some point.
+
+Traditionally state machines are added to a existing project when
+developer realizes that code base is starting to look like a plate
+full of spaghetti. Spaghetti code looks like never ending hierarchical
+structure of IFs, ELSEs and BREAK clauses and probably compiler should
+ask developer to go home when things are starting to look too complex.
+
+This reference documentations contains following parts.
+
+<<introduction>> introduction to this reference documentation
+
+<<statemachine>> describes the usage of Spring State Machine(SSM)
+
+<<statemachine-examples>> more detailed state machine samples
+
+<<appendices>> generic info about used material and state machines
+

docs/src/reference/asciidoc/samples/.gitignore

@@ -0,0 +1,2 @@
+*.java
+

docs/src/reference/asciidoc/sm-examples.adoc

@@ -0,0 +1,10 @@
+[[statemachine-examples]]
+= Statemachine Examples
+
+This part of the reference documentation explains the use of state
+machines as sample code together with a uml state charts.
+
+== Simple Statemachine
+
+TBD
+

docs/src/reference/asciidoc/sm.adoc

@@ -1,5 +1,33 @@
 [[statemachine]]
-= State Machine
+= Spring and Statemachine
+
+This part of the reference documentation explains the core functionality
+that Spring Statemachine provides to any Spring based application.
+
+<<sm-config>> describes the generic configuration support.
+
+[[sm-config]]
+== Statemachine Configuration
+
+One of the common tasks when using a Statemachine is to design its
+runtime configuration. This chapter will focus on How Spring
+Statemachine is configured and how it leverages Spring's lightweight
+IoC containers to simplify the application internals to make it more
+manageable.
+
+=== Using the Spring Statemachine JavaConfig
+
+[source,java,indent=0]
+----
+include::samples/DocsConfigurationSampleTests.java[tags=snippetA]
+----
+
+
+== Context Ingregration
+
 TBD
 
+=== Annotation Support
+
+TBD
 

spring-statemachine-core/src/test/java/org/springframework/statemachine/docs/DocsConfigurationSampleTests.java

@@ -0,0 +1,51 @@
+/*
+ * Copyright 2015 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.statemachine.docs;
+
+import java.util.EnumSet;
+
+import org.springframework.context.annotation.Configuration;
+import org.springframework.statemachine.AbstractStateMachineTests;
+import org.springframework.statemachine.config.EnableStateMachine;
+import org.springframework.statemachine.config.EnumStateMachineConfigurerAdapter;
+import org.springframework.statemachine.config.builders.StateMachineStateConfigurer;
+
+/**
+ * Tests for state machine configuration.
+ *
+ * @author Janne Valkealahti
+ *
+ */
+public class DocsConfigurationSampleTests extends AbstractStateMachineTests {
+
+// tag::snippetA[]
+	@Configuration
+	@EnableStateMachine
+	public static class Config1 extends EnumStateMachineConfigurerAdapter<MyStates, MyEvents> {
+
+		@Override
+		public void configure(StateMachineStateConfigurer<MyStates, MyEvents> states) throws Exception {
+			states
+				.withStates()
+					.initial(MyStates.S1)
+					.end(MyStates.SF)
+					.states(EnumSet.allOf(MyStates.class));
+		}
+
+	}
+// end::snippetA[]
+
+}

spring-statemachine-core/src/test/java/org/springframework/statemachine/docs/MyEvents.java

@@ -0,0 +1,7 @@
+package org.springframework.statemachine.docs;
+
+//tag::snippetA[]
+public enum MyEvents {
+    E1,E2,E3,E4,EF
+}
+//end::snippetA[]

spring-statemachine-core/src/test/java/org/springframework/statemachine/docs/MyStates.java

@@ -0,0 +1,7 @@
+package org.springframework.statemachine.docs;
+
+//tag::snippetA[]
+public enum MyStates {
+    SI,S1,S2,S3,S4,SF
+}
+//end::snippetA[]