Improve documentation and provides a simple example

docs/source/index.rst

@@ -22,3 +22,27 @@ Installing
 It is easy to obtain the latest released version via ``pip``::
 
     pip install steinlib
+
+Usage
+=====
+
+In order to use the parsed structures, two main components are required:
+ - A *parser*, that will be responsible for parsing the structure, and;
+ - A *instance*, where the parser will invoke callbacks when known structures are found
+
+So, let's see an example about how it works.
+
+Starting with an STP file available on Steinlib official website:
+
+ .. literalinclude:: ../../examples/hello.stp
+
+It is possible to observe this file contains three main components:
+ - a **header line**;
+ - a set of delimited **sections** and;
+ - the **end of file** marker.
+
+This *parser* will identify all these small pieces of the STP file and use it to
+trigger functions on your *instance*. This is the key concept used to create
+this module.
+
+

examples/hello.stp

@@ -0,0 +1,41 @@
+33D32945 STP File, STP Format Version 1.0
+
+SECTION Comment
+Name    "Odd Wheel"
+Creator "T. Koch, A. Martin and S. Voss"
+Remark  "Example used to describe the STP data format"
+END
+
+SECTION Graph
+Nodes 7
+Edges 9
+E 1 2 1
+E 1 4 1
+E 1 6 1
+E 2 3 1
+E 3 4 1
+E 4 5 1
+E 5 6 1
+E 6 7 1
+E 7 2 1
+END
+
+SECTION Terminals
+Terminals 4
+T 1
+T 3
+T 5
+T 7
+END
+
+SECTION Coordinates
+DD 1  80 50
+DD 2  30 50
+DD 3  55  5
+DD 4 105  5
+DD 5 130 50
+DD 6 105 95
+DD 7  55 95
+END
+
+EOF

examples/hello_steinlib.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+from steinlib.instance import SteinlibInstance
+from steinlib.parser import SteinlibParser
+
+import sys
+
+
+class MySteinlibInstance(SteinlibInstance):
+    """
+    This is my first steinlib parser!
+    """
+
+    def comment(self, raw_args, lis_args):
+        print "Comment section found"
+
+    def coordinates(self, raw_args, list_args):
+        print "Coordinates section found"
+
+    def eof(self, raw_args, list_args):
+        print "End of file found"
+
+    def graph(self, raw_args, list_args):
+        print "Graph section found"
+
+    def header(self, raw_args, list_args):
+        print "Header found"
+
+    def terminals(self, raw_args, list_args):
+        print "Terminals section found"
+
+
+if __name__ == "__main__":
+    my_class = MySteinlibInstance()
+    with open(sys.argv[1]) as my_file:
+        my_parser = SteinlibParser(my_file, my_class)
+        my_parser.parse()