Sphinx docs coming along.

It's so pretty!  Make me want to write more docs.  :-)

Some weird bug parsing the library.py module though.  D'oh!

joy/utils/pretty_print.py

@@ -19,16 +19,6 @@
 #
 '''
 Pretty printing support.
-
-This is what does the formatting, e.g.:
-
-           . 23 18 mul 99 add
-        23 . 18 mul 99 add
-     23 18 . mul 99 add
-       414 . 99 add
-    414 99 . add
-       513 . 
-
 '''
 # (Kinda clunky and hacky.  This should be swapped out in favor of much
 # smarter stuff.)
@@ -38,6 +28,18 @@ from .stack import expression_to_string, stack_to_string
 
 
 class TracePrinter(object):
+  '''
+  This is what does the formatting, e.g.::
+
+    Joy? 23 18 * 99 +
+           . 23 18 mul 99 add
+        23 . 18 mul 99 add
+     23 18 . mul 99 add
+       414 . 99 add
+    414 99 . add
+       513 . 
+
+  '''
 
   def __init__(self):
     self.history = []

joy/utils/stack.py

@@ -18,64 +18,60 @@
 #    along with Thun.  If not see <http://www.gnu.org/licenses/>.
 #
 '''
-
-
-§ Stack
-
-
-When talking about Joy we use the terms "stack", "list", "sequence" and
-"aggregate" to mean the same thing: a simple datatype that permits
-certain operations such as iterating and pushing and popping values from
-(at least) one end.
+When talking about Joy we use the terms "stack", "list", "sequence",
+"quote" and others to mean the same thing: a simple linear datatype that
+permits certain operations such as iterating and pushing and popping
+values from (at least) one end.
 
 We use the venerable two-tuple recursive form of sequences where the
 empty tuple () is the empty stack and (head, rest) gives the recursive
-form of a stack with one or more items on it.
+form of a stack with one or more items on it::
 
-  ()
-  (1, ())
-  (2, (1, ()))
-  (3, (2, (1, ())))
-  ...
+    stack := () | (item, stack)
 
-And so on.
+Putting some numbers onto a stack::
 
-
-We have two very simple functions to build up a stack from a Python
-iterable and also to iterate through a stack and yield its items
-one-by-one in order, and two functions to generate string representations
-of stacks:
-
-  list_to_stack()
-
-  iter_stack()
-
-  expression_to_string()  (prints left-to-right)
-
-  stack_to_string()  (prints right-to-left)
-
-
-A word about the stack data structure.
+    ()
+    (1, ())
+    (2, (1, ()))
+    (3, (2, (1, ())))
+    ...
 
 Python has very nice "tuple packing and unpacking" in its syntax which
 means we can directly "unpack" the expected arguments to a Joy function.
 
-For example:
+For example::
 
-  def dup(stack):
-    head, tail = stack
+  def dup((head, tail)):
     return head, (head, tail)
 
 We replace the argument "stack" by the expected structure of the stack,
-in this case "(head, tail)", and Python takes care of de-structuring the
-incoming argument and assigning values to the names.  Note that Python
+in this case "(head, tail)", and Python takes care of unpacking the
+incoming tuple and assigning values to the names.  (Note that Python
 syntax doesn't require parentheses around tuples used in expressions
-where they would be redundant.
+where they would be redundant.)
 '''
 
+##We have two very simple functions to build up a stack from a Python
+##iterable and also to iterate through a stack and yield its items
+##one-by-one in order, and two functions to generate string representations
+##of stacks::
+##
+##  list_to_stack()
+##
+##  iter_stack()
+##
+##  expression_to_string()  (prints left-to-right)
+##
+##  stack_to_string()  (prints right-to-left)
+##
+##
+##A word about the stack data structure.
+
+
 
 def list_to_stack(el, stack=()):
-  '''Convert a list (or other sequence) to a stack.
+  '''Convert a Python list (or other sequence) to a Joy stack::
 
   [1, 2, 3] -> (1, (2, (3, ())))
 
@@ -96,9 +92,9 @@ def stack_to_string(stack):
   '''
   Return a "pretty print" string for a stack.
 
-  The items are written right-to-left:
+  The items are written right-to-left::
 
-  (top, (second, ...)) -> '... second top'
+    (top, (second, ...)) -> '... second top'
   '''
   f = lambda stack: reversed(list(iter_stack(stack)))
   return _to_string(stack, f)
@@ -108,9 +104,9 @@ def expression_to_string(expression):
   '''
   Return a "pretty print" string for a expression.
 
-  The items are written left-to-right:
+  The items are written left-to-right::
 
-  (top, (second, ...)) -> 'top second ...'
+    (top, (second, ...)) -> 'top second ...'
   '''
   return _to_string(expression, iter_stack)