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!

docs/sphinx_docs/index.rst

@@ -6,13 +6,15 @@
 Thun Documentation
 ==================
 
-Hey
+Hey there!
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
-There!
+   stack
+   parser
+   pretty
 
 .. automodule:: joy.joy
    :members:

docs/sphinx_docs/library.rst

@@ -0,0 +1,9 @@
+
+Functions, Combinators and Definitions
+======================================
+
+
+. . automodule:: joy.library
+   :members:
+
+

docs/sphinx_docs/parser.rst

@@ -0,0 +1,9 @@
+
+Parsing Text into Joy Expressions
+=================================
+
+
+.. automodule:: joy.parser
+   :members:
+
+

docs/sphinx_docs/pretty.rst

@@ -0,0 +1,9 @@
+
+Tracing Joy Execution
+=====================
+
+
+.. automodule:: joy.utils.pretty_print
+   :members:
+
+

docs/sphinx_docs/stack.rst

@@ -0,0 +1,9 @@
+
+Stack or Quote or Sequence or List...
+=====================================
+
+
+.. automodule:: joy.utils.stack
+   :members:
+
+

joy/joy.py

@@ -64,6 +64,12 @@ from .utils.pretty_print import TracePrinter
 def joy(stack, expression, dictionary, viewer=None):
   '''
   Evaluate the Joy expression on the stack.
+
+  :param quote stack: The stack.
+  :param quote expression: The expression to evaluate.
+  :param dict dictionary: A `dict` mapping names to Joy functions.
+  :param function viewer: Optional viewer function.
+
   '''
   while expression:
 

joy/parser.py

@@ -18,45 +18,55 @@
 #    along with Thun.  If not see <http://www.gnu.org/licenses/>.
 #
 '''
+This module exports a single function for converting text to a joy
+expression as well as a single Symbol class and a single Exception type.
+
+The Symbol string class is used by the interpreter to recognize literals
+by the fact that they are not Symbol objects.
+
+A crude grammar::
+
+  joy = term*
+  term = int | float | string | '[' joy ']' | function
+
+A Joy expression is a sequence of zero or more terms
 
 
-§ Converting text to a joy expression.
-
-This module exports a single function:
-
-  text_to_expression(text)
-
-As well as a single Symbol class and a single Exception type:
-
-  ParseError
-
-When supplied with a string this function returns a Python datastructure
-that represents the Joy datastructure described by the text expression.
-Any unbalanced square brackets will raise a ParseError.
 '''
+#TODO: explain the details of float lits and strings.
 from re import Scanner
 from .utils.stack import list_to_stack
 
 
 class Symbol(str):
+  '''A string class that represents Joy function names.'''
   __repr__ = str.__str__
 
 
 def text_to_expression(text):
-  '''
+  '''Convert a string to a Joy expression.
-  Convert a text to a Joy expression.
+
+  When supplied with a string this function returns a Python datastructure
+  that represents the Joy datastructure described by the text expression.
+  Any unbalanced square brackets will raise a ParseError.
+
+  :param str text: Text to convert.
+  :rtype: quote
+  :raises ParseError: if the parse fails.
   '''
   return _parse(_tokenize(text))
 
 
-class ParseError(ValueError): pass
+class ParseError(ValueError):
+  '''Raised when there is a error while parsing text.'''
 
 
 def _tokenize(text):
-  '''
+  '''Convert a text into a stream of tokens.
-  Convert a text into a stream of tokens, converting symbols using
+
-  symbol(token).  Raise ValueError (with some of the failing text)
+  Converts function names to Symbols.
-  if the scan fails.
+
+  Raise ParseError (with some of the failing text) if the scan fails.
   '''
   tokens, rest = _scanner.scan(text)
   if rest:

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/>.
 #
 '''
-
+When talking about Joy we use the terms "stack", "list", "sequence",
-
+"quote" and others to mean the same thing: a simple linear datatype that
-§ Stack
+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" 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.
 
 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::
 
-  ()
+    stack := () | (item, stack)
-  (1, ())
-  (2, (1, ()))
-  (3, (2, (1, ())))
-  ...
 
-And so on.
+Putting some numbers onto a stack::
 
-
+    ()
-We have two very simple functions to build up a stack from a Python
+    (1, ())
-iterable and also to iterate through a stack and yield its items
+    (2, (1, ()))
-one-by-one in order, and two functions to generate string representations
+    (3, (2, (1, ())))
-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.
 
 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):
+  def dup((head, tail)):
-    head, tail = stack
     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
+in this case "(head, tail)", and Python takes care of unpacking the
-incoming argument and assigning values to the names.  Note that Python
+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)