Show transitions initiated by API requests

This updates the state machine diagram and documentation to indicate
which transitions are initiated by API requests versus the ones that
are internally done by the conductor. Stable states are highlighted
a bit.

Change-Id: I1a2de81b14696286f1da47c06374ad235962c849
Closes-Bug: #1527316

1 files changed, 48 insertions, 4 deletions

diff --git a/tools/states_to_dot.py b/tools/states_to_dot.py
index c452351c2..16b436571 100755
--- a/tools/states_to_dot.py
+++ b/tools/states_to_dot.py
@@ -66,18 +66,62 @@ def main():
     if options.filename is None:
         options.filename = 'states.%s' % options.format
 
+    def node_attrs(state):
+        """Attributes used for drawing the nodes (states).
+
+        The user can perform actions on stable states (and in a few other
+        cases), so we distinguish the stable states from the other states by
+        highlighting the node. Non-stable states are labelled with gray.
+
+        This is a callback method used by pydot.convert().
+
+        :param state: name of state
+        :returns: A dictionary with graphic attributes used for displaying
+                  the state.
+        """
+        attrs = map_color(state)
+        if source.is_stable(state):
+            attrs['penwidth'] = 1.7
+        else:
+            if 'fontcolor' not in attrs:
+                attrs['fontcolor'] = 'gray'
+        return attrs
+
     def edge_attrs(start_state, event, end_state):
+        """Attributes used for drawing the edges (transitions).
+
+        There are two types of transitions; the ones that the user can
+        initiate and the ones that are done internally by the conductor.
+        The user-initiated ones are shown with '(via API'); the others are
+        in gray.
+
+        This is a callback method used by pydot.convert().
+
+        :param start_state: name of the start state
+        :param event: the event, a string
+        :param end_state: name of the end state (unused)
+        :returns: A dictionary with graphic attributes used for displaying
+                  the transition.
+        """
+        if not options.labels:
+            return {}
+
+        translations = {'delete': 'deleted', 'deploy': 'active'}
         attrs = {}
-        if options.labels:
-            attrs['label'] = "on_%s" % event
-            attrs.update(map_color(event))
+        attrs['fontsize'] = 12
+        attrs['label'] = translations.get(event, event)
+        if (source.is_stable(start_state) or 'fail' in start_state
+            or event in ('abort', 'delete')):
+            attrs['label'] += " (via API)"
+        else:
+            attrs['fontcolor'] = 'gray'
         return attrs
 
     source = states.machine
     graph_name = '"Ironic states"'
     graph_attrs = {'size': 0}
     g = pydot.convert(source, graph_name, graph_attrs=graph_attrs,
-                      node_attrs_cb=map_color, edge_attrs_cb=edge_attrs)
+                      node_attrs_cb=node_attrs, edge_attrs_cb=edge_attrs)
 
     print_header(graph_name)
     print(g.to_string().strip())