Add simple machine doctest(ed) example into docs

Change-Id: I9017b6972a06b57b0ae1c997640fbb51b6c4bea6

doc/source/conf.py

@@ -22,7 +22,7 @@ sys.path.insert(0, os.path.abspath('../..'))
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
     'sphinx.ext.autodoc',
-    #'sphinx.ext.intersphinx',
+    'sphinx.ext.doctest',
     'oslosphinx'
 ]
 

doc/source/examples.rst

@@ -0,0 +1,66 @@
+========
+Examples
+========
+
+-------------------------
+Creating a simple machine
+-------------------------
+
+.. testcode::
+
+    from automaton import machines
+    m = machines.FiniteMachine()
+    m.add_state('up')
+    m.add_state('down')
+    m.add_transition('down', 'up', 'jump')
+    m.add_transition('up', 'down', 'fall')
+    m.default_start_state = 'down'
+    print(m.pformat())
+
+**Expected output:**
+
+.. testoutput::
+
+    +---------+-------+------+----------+---------+
+    |  Start  | Event | End  | On Enter | On Exit |
+    +---------+-------+------+----------+---------+
+    | down[^] |  jump |  up  |    .     |    .    |
+    |    up   |  fall | down |    .     |    .    |
+    +---------+-------+------+----------+---------+
+
+------------------------------
+Transitioning a simple machine
+------------------------------
+
+.. testcode::
+
+    m.initialize()
+    m.process_event('jump')
+    print(m.pformat())
+    print(m.current_state)
+    print(m.terminated)
+    m.process_event('fall')
+    print(m.pformat())
+    print(m.current_state)
+
+**Expected output:**
+
+.. testoutput::
+
+    +---------+-------+------+----------+---------+
+    |  Start  | Event | End  | On Enter | On Exit |
+    +---------+-------+------+----------+---------+
+    | down[^] |  jump |  up  |    .     |    .    |
+    |   @up   |  fall | down |    .     |    .    |
+    +---------+-------+------+----------+---------+
+    up
+    False
+    +----------+-------+------+----------+---------+
+    |  Start   | Event | End  | On Enter | On Exit |
+    +----------+-------+------+----------+---------+
+    | @down[^] |  jump |  up  |    .     |    .    |
+    |    up    |  fall | down |    .     |    .    |
+    +----------+-------+------+----------+---------+
+    down
+    False
+

doc/source/index.rst

@@ -9,6 +9,7 @@ Friendly state machines for python.
    features
    api
    installation
+   examples
    contributing
 
 Indices and tables