Add a graphical depiction of the object graph to the docs.

Also, stop calling the graph a hierarchy or a tree. We'll now consistently
refer to it as an "object graph".

doc-src/index.py

@@ -35,7 +35,7 @@ def py(self, path, **kwargs):
 
 pages = [
     Page("index.html", "Introduction"),
-    Page("objects.html", "Object Hierarchy"),
+    Page("objects.html", "Object Graph"),
     Directory("objects"),
     Page("configuration.html", "Configuration"),
     Directory("configuration"),

doc-src/objects.html

@@ -1,6 +1,6 @@
 
-Qtile's public API consists of a hierarchy of nodes, each with a set of
-associated commands. The same API serves a number of different purposes:
+Qtile's public API consists of a graph of nodes, each with a set of associated
+commands. The same API serves a number of different purposes:
 
     - Commands can be bound to keys in the Qtile configuration file. 
     - Commands can be called manually through __qsh__, the Qtile shell.
@@ -10,43 +10,26 @@
 can be accessed from its built-in help command, and are not documented here.
 
 
-Object Hierarchy
-================
+Object Graph
+============
 
-    Qtile's object hierarchy consists of seven node types: __layout__,
-    __window__, __group__, __bar__, __widget__, __screen__, and a special root
-    node that lies at the top of the tree. Each node has a set of associated
-    commands, a set of children, and a set of keys.  This is what the hierarchy
-    looks like at a high level:
+    Qtile's object graph consists of seven node types: __layout__, __window__,
+    __group__, __bar__, __widget__, __screen__, and a special __root__ node.
+    Individual nodes are addressed by a path specification that starts at the
+    root node, and follows the edges of the graph. Each node has a set of
+    associated commands, a set of children, and a set of keys.  This is what
+    the graph looks like:
 
-<pre>
-root
-    bar
-        screen
-    group
-        layout
-        screen
-        window
-    layout
-        group
-        screen
-        window
-    screen
-        bar
-        layout
-        window
-    widget
-        bar
-        group
-        screen
-    window
-        group
-        screen
-        layout
-</pre>
+<center>
+<img src="objgraph.png">
+</center>
+
+    Each arrow can be read as "holds a reference to". So, we would say that a
+    __widget__ object _holds a reference to_ objects of type __bar__,
+    __screen__ and __group__, exposed as attributes with the same names.
 
     Lets start with a simple example. The following script runs the __status__
-    command on the root node of the command tree (which, in this case, is the
+    command on the root node of the command graph (which, in this case, is the
     Client object):
 
 <!--(block | pySyntax)-->
@@ -55,16 +38,16 @@
 print c.status()
 <!--(end)-->
 
-    Children are exposed as attributes on each node, so we can access the
-    "info" command on the group child node like so:
+    From the graph, we can see that the root node holds a reference to
+    __group__ nodes. We can access the "info" command on the current group like
+    so:
 
 <!--(block | pySyntax)-->
 c.group.info()
 <!--(end)-->
 
-    In the example above, __c.group__ specifies the _current_ group. To access
-    a specific group, regardless of whether or not it is current, we use the
-    Python containment syntax:
+    To access a specific group, regardless of whether or not it is current, we
+    use the Python containment syntax:
 
 <!--(block | pySyntax)-->
 c.group["b"].info()
@@ -74,7 +57,7 @@
     accessed by simply leaving the key specifier out. The key specifier is
     mandatory for __widget__ and __bar__ nodes. 
 
-    We can now drill down deeper in the hierarchy. To access the screen
+    We can now drill down deeper in the graph. To access the screen
     currently displaying group "b", we can do this:
 
 <!--(block | pySyntax)-->
@@ -89,7 +72,7 @@
 libqtile.command.CommandError: No object screen in path 'group['b'].screen'
 </pre>
 
-    The hierarchy is not a tree, since it can contain cycles. This path
+    The graph is not a tree, since it can contain cycles. This path
     (redundantly) specifies the group belonging to the screen that belongs to
     group "b":
 

doc-src/qsh.html

@@ -7,10 +7,10 @@
 file. See the GNU Readline documentation for more information.
 
 
-Navigating the Object Hierarchy
-===============================
+Navigating the Object Graph
+===========================
 
-The shell presents a filesystem-like interface to the object hierarchy - the
+The shell presents a filesystem-like interface to the object graph - the
 builtin "cd" and "ls" commmands act like their familiar shell counterparts:
 
 <pre>

resources/README

@@ -0,0 +1,7 @@
+
+
+objgraph.dot 
+
+    The Qtile object graph, in graphviz dot format. Render like so:
+
+        circo -Tpng objgraph.dot > objgraph.png

resources/objgraph.dot

@@ -0,0 +1,34 @@
+
+digraph G {
+    root = "root";
+    splines = true;
+
+    root -> bar;
+    root -> group;
+    root -> layout;
+    root -> screen;
+    root -> widget;
+    root -> window;
+
+    bar -> screen;
+
+    group -> layout;
+    group -> screen;
+    group -> window;
+
+    layout -> group;
+    layout -> screen;
+    layout -> window;
+
+    screen -> bar;
+    screen -> layout;
+    screen -> window;
+
+    widget -> bar;
+    widget -> group;
+    widget -> screen;
+
+    window -> group;
+    window -> screen;
+    window -> layout;
+}