Adding more documentation in the companion site

README

@@ -32,92 +32,9 @@ In addition, a binary distribution, continuously updated, is available at:
     http://dist.thingml.org/trio/trio-dist.zip
 
 
+3. PROJECT DOCUMENTATION
+------------------------
 
-3. HOW TO RUN TRIO
-------------------
+The documentation of Trio (in version 0.2-SNAPSHOT) is available at:
 
-Trio is a java application, which should be run from the command line. The 
-following example show its primary usage.
-
-
-Usage: trio [options] input.trio
-where 'options' are:
-  -o, --observe=TAG  the tag of the components whose activity shall be observed
-  -c, --control=TAG  the tag of the components whose activity shall be controlled
-  -r, --runs=INTEGER the number of sample for statistical evidence
-  -t, --trace=FILE   the file where the generated data shall be stored
-Example: trio -o result.csv --run=10000 system.trio
-
-
-Below is an example of output of succesful invocation
-
-$> java -jar trio-bundle.jar -o service -c infra -t trace.csv samples/sensapp_topo4.trio
-Trio v0.1 -- Topology Robustness IndicatOr
-Copyright (C) 2014 - SINTEF ICT
-Licensed under LGPLv3
-
-SYSTEM: SensApp, topology no. 4
-SCENARIO: Robustness of the 'service' layer to failure in the 'infra' layer
-INDICATORS:
- + Robustness: 0.0297
- + Five most sensitive components:
-   1: 1.7375e+00  VM2
-   2: 8.2376e-01  VM1
-   3: 6.8183e-01  VM4
-   4: 6.6244e-01  VM3
-   5: 5.6873e-01  VM5
- + Five most harmful sequences:
-   1: 1.9200e-01 [none,  VM2]
-   2: 5.6990e-02 [none,  VM3,  VM2]
-   3: 5.2990e-02 [none,  VM4,  VM2]
-   4: 5.1991e-02 [none,  VM1,  VM2]
-   5: 3.1994e-02 [none,  VM5,  VM2]
-
-That's all folks!
-
-
-4. HOW TO BUILD TRIO
---------------------
-
-$> mvn clean package
-
-
-
-5. HOW TO RELEASE TRIO
-----------------------
-
-Before to create a release, one should ensure the following:
-
- - Read/write access to the git repository 
-
- - Valid credentials to connect on the "deployment" server are
-   configured in .m2/settings.xml
-
-The configuration of the SCM maven plugin can be tested using the
-following command:
-
-$> mvn scm:validate
-
-Under Windows, one shall set up an ssh agent to avoid that the git
-command hang waiting for a passphrase. The following commands are
-necessary (run on the git-bash):
-
-$> eval `ssh-agent`
-$> env | grep SSH
-$> ssh-add "/c/Users/franckc/.ssh/id_rsa"
-   enter passphrase : XXXXXXXX
-
-The Maven release plugin can be run in a "dryRun" mode using the
-option '-DdryRun=true-'. We recommend to get the 'dry run' before to
-run the 'release:prepare' command.
-
-$> mvn --batch-mode release:prepare -DreleaseVersion=0.1 -DdevelopmentVersion=0.2-SNAPSHOT
-
-$> mvn release:perform
-
-If anything goes wrong during the prepare or perform command, on can
-revert the info committed in the repository using the following
-commands:
-
-$> git reset --hard <id of the commit you want to reset to>
-$> git push origin master --force
+    http://fchauvel.github.io/trio/0.2-SNAPSHOT/

pom.xml

@@ -7,9 +7,16 @@
     <artifactId>eu.diversify.trio</artifactId>
     <version>0.2-SNAPSHOT</version>
     <name>TRIO</name>
+    <url>http://fchauvel.github.com/trio</url>
+    <description>
+        TRIO is a simple domain specific language (DSL) used to describe the topology
+        of software deployment and to gain insight regarding their robustness.
+    </description>
+
 
     <properties>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+        <github.global.server>github</github.global.server>
     </properties>
 
     <licenses>
@@ -85,10 +92,17 @@
             <url>http://maven.thingml.org/archiva/repository/thingml-snapshot/</url>
         </snapshotRepository>
 
+
+        <site>
+            <id>github-pages</id>
+            <name>github-pages trought GitHub site plugin</name>
+            <url>http://fchauvel.github.com/trio</url>
+        </site>
+
     </distributionManagement>
 
     <issueManagement>
-        <url>https://github.com/DIVERSIFY-project/disco/issues</url>
+        <url>https://github.com/fchauvel/trio/issues</url>
     </issueManagement>
 
     <ciManagement>
@@ -399,6 +413,25 @@
                 </dependencies>
             </plugin>
 
+            <!-- Publishing maven site on GitHub pages -->
+            <plugin>
+                <groupId>com.github.github</groupId>
+                <artifactId>site-maven-plugin</artifactId>
+                <version>0.10</version>
+                <configuration>
+                    <message>Updating site for Trio ${project.version}</message>
+                    <path>${project.version}</path>
+                    <merge>true</merge>
+                </configuration>
+                <executions>
+                    <execution>
+                        <goals>
+                            <goal>site</goal>
+                        </goals>
+                        <phase>site</phase>
+                    </execution>
+                </executions>
+            </plugin>
         </plugins>
 
     </build>

src/site/markdown/how_to_contribute.md

@@ -0,0 +1,65 @@
+## How to contribute?
+
+### How to fetch the source code
+
+Trio is an open-source Java application, whose source code is available on 
+Github at the following address: 
+
+https://github.com/fchauvel/trio/
+
+
+### How to build Trio
+
+The Trio code base follows the Maven convention. The project can be build,
+tested, packaged and installed locally by running the command:
+
+    $> mvn clean install
+
+
+### How to release a new version
+
+Before to create a release, one should ensure the following:
+
+ - Read/write access to the git repository 
+
+ - Valid credentials to connect on the "deployment" server are
+   configured in .m2/settings.xml
+
+The configuration of the SCM maven plugin can be tested using the
+following command:
+
+    $> mvn scm:validate
+
+Under Windows, one shall set up an ssh agent to avoid that the git
+command hang waiting for a passphrase. The following commands are
+necessary (run on the git-bash):
+
+    $> eval `ssh-agent`
+    $> env | grep SSH
+    $> ssh-add "/c/Users/Bobby/.ssh/id_rsa"
+       enter passphrase : XXXXXXXX
+
+The Maven release plugin can be run in a "dryRun" mode using the
+option '-DdryRun=true-'. We recommend to get the 'dry run' before to
+run the 'release:prepare' command.
+
+    $> mvn --batch-mode release:prepare -DdryRun=true -DreleaseVersion=0.1 -DdevelopmentVersion=0.2-SNAPSHOT
+    $> mvn --batch-mode release:prepare -Dresume=false -DreleaseVersion=0.1 -DdevelopmentVersion=0.2-SNAPSHOT
+    $> mvn release:perform
+
+If anything goes wrong during the 'perform' command, on can
+revert the info committed in the repository using the following
+commands:
+
+    $> git reset --hard <id of the commit you want to reset to>
+    $> git push origin master --force
+
+Tags that have been created by the release plugin will not be removed by the 
+previous commands, and must remove manually, as shown below. The first command 
+retrieves all the existing tags, and the next two remove and publish the removal
+respectively.
+
+    $> git tag
+    my-app-0.1
+    $> git tag -d my-app-0.1
+    $> git push origin :refs/tags/my-app-0.1

src/site/markdown/usage.md

@@ -27,4 +27,122 @@ the strength of the statistical evidence associated with the output indicators.
 
 The following command illustrates how to run TRIO from the command line
 
-    $> java -jar trio-final.jar my-deployment.json 1000
+Trio is a java application, which should be run from the command line. The 
+following example show its primary usage.
+
+    Usage: trio [options] input.trio
+    where 'options' are:
+      -o, --observe=TAG  the tag of the components whose activity shall be observed
+      -c, --control=TAG  the tag of the components whose activity shall be controlled
+      -r, --runs=INTEGER the number of sample for statistical evidence
+      -t, --trace=FILE   the file where the generated data shall be stored
+
+Example: 
+
+    trio -o result.csv --run=10000 system.trio
+
+Below is an example of output of successful invocation
+
+    $> java -jar trio-bundle.jar -o service -c infra -t trace.csv samples/sensapp_topo4.trio
+    Trio v0.1 -- Topology Robustness IndicatOr
+    Copyright (C) 2014 - SINTEF ICT
+    Licensed under LGPLv3
+
+    SYSTEM: SensApp, topology no. 4
+    SCENARIO: Robustness of the 'service' layer to failure in the 'infra' layer
+    INDICATORS:
+     + Robustness: 0.0297
+     + Five most sensitive components:
+       1: 1.7375e+00  VM2
+       2: 8.2376e-01  VM1
+       3: 6.8183e-01  VM4
+       4: 6.6244e-01  VM3
+       5: 5.6873e-01  VM5
+     + Five most harmful sequences:
+       1: 1.9200e-01 [none,  VM2]
+       2: 5.6990e-02 [none,  VM3,  VM2]
+       3: 5.2990e-02 [none,  VM4,  VM2]
+       4: 5.1991e-02 [none,  VM1,  VM2]
+       5: 3.1994e-02 [none,  VM5,  VM2]
+
+    That's all folks!
+
+
+### Describing the topology of the system
+
+The topology under study shall be described in a separate text file, as shown in the
+example below, where we described the deployment of the SensApp system. SensApp is made
+of five REST services (i.e., Admin, Notifier, Registry, Dispatcher and Storage), 
+that must be run on the top of servlet containers (SCX), themselves requiring 
+Java Runtime Environment (JRE) to run properly. The topology thus includes all 
+these services and the related platform as well as the underlying infrastructure 
+(physical or virtual machine) on which these software component are deployed.
+
+    #
+    # The SensApp services and their dependencies
+    #
+
+    system: 
+        'SensApp, topology no. 1'
+
+    components:
+        - Admin         requires    Notifier and Registry and Storage and SC1
+        - Notifier      requires    SC2
+        - Registry      requires    Storage and SC2
+        - Dispatcher    requires    Notifier and Registry and Storage and SC2
+        - Storage       requires    DB and VM2
+        - DB            requires    VM2
+        - SC1           requires    JRE1
+        - SC2           requires    JRE2
+        - JRE1          requires    VM1
+        - JRE2          requires    VM2
+        - VM1
+        - VM2
+
+    tags:
+        - 'infra'     on  VM1, VM2
+        - 'platform'  on  DB, SC1, SC2, JRE1, JRE2
+        - 'service'   on  Admin, Registry, Storage, Dispatcher, Notifier
+
+
+The description of the system is made of three sections: "system", "components" 
+and "tags". 
+
+ - The "system" section associates a name to the system;
+ - the "components" section captures the topology as an assembly of components 
+(and their dependencies);
+ - the "tags" section let the user partitions the topology by arbitrarily 
+classifying components.
+
+Technical readers may found a complete description of the language used to 
+capture topologies in the associated ANTLR grammar, available at: 
+https://github.com/fchauvel/trio/blob/master/src/main/antlr4/eu/diversify/trio/builder/Trio.g4
+
+
+#### Expressing dependencies between components
+
+The most important section is the one entitled "components". It describes the 
+components (in the broadest meaning of the term) and their dependencies. Dependencies are 
+specified by the (optional) "requires" clause, which is followed by a logical condition
+over the other components. For instance, in the above example, the expression:
+
+    - Registry      requires    Storage and SC2
+
+states that the "registry" service of SensApp will remain operational as long as
+the Storage component and the underlying Servlet container (i.e., SC2) are 
+operational as well. These logical expressions will permit to propagate failures and,
+in turn, to evaluate the robustness of the system.
+
+#### Partitioning the topology
+
+In many cases one may not be interested in the overall robustness, but in the 
+robustness of a subpart of the system with respect to failure of another. Trio let you 
+partition the topology by tagging the components in the "tag" section. For instance,
+in the above example, the line:
+
+    - 'infra'     on  VM1, VM2
+
+states that both components "VM1" and "VM2" are tagged as "infra". Along with 
+other tagging clauses, they will permit to evaluate the robustness of the 
+infrastructure (so called "infra"), with respect to others partitions 
+(e.g., platform or services).

src/site/site.xml

@@ -29,6 +29,7 @@
         </head>
         <menu name="Documentation">
             <item name="Usage" href="usage.html" />
+             <item name="How to contribute?" href="how_to_contribute.html" />
         </menu>
 
         <links>