Updated docs.

Details:

Fixed up yajl_parse docs and added quick examples.

doc/source/index.rst

@@ -29,7 +29,7 @@ For the development version you may visit
 Alternatives
 ------------
 
-Another python library that wraps yajl for python is 
+Another python library that wraps yajl for python is
 `py-yajl <http://github.com/rtyler/py-yajl/>`_. py-yajl creates an
 alternative to the built in json.loads and json.dumps using yajl. On the
 other hand, yajl-py wraps only yajl's functionality giving the user the
@@ -58,7 +58,73 @@ that one can follow the logic.
 Quick Example
 .............
 
-.. write some quick example here
+Parsing
++++++++
+.. code-block:: python
+
+    import sys
+    from yajl import *
+
+    # Sample callbacks, which output some debug info
+    # these are examples to show off the yajl parser
+    class ContentHandler(YajlContentHandler):
+        def __init__(self):
+            self.out = sys.stdout
+        def yajl_null(self, ctx):
+            self.out.write("null\n" )
+        def yajl_boolean(self, ctx, boolVal):
+            self.out.write("bool: %s\n" %('true' if boolVal else 'false'))
+        def yajl_integer(self, ctx, integerVal):
+            self.out.write("integer: %s\n" %integerVal)
+        def yajl_double(self, ctx, doubleVal):
+            self.out.write("double: %s\n" %doubleVal)
+        def yajl_number(self, ctx, stringNum):
+            ''' Since this is defined both integer and double callbacks are useless '''
+            num = float(stringNum) if '.' in stringNum else int(stringNum)
+            self.out.write("number: %s\n" %num)
+        def yajl_string(self, ctx, stringVal):
+            self.out.write("string: '%s'\n" %stringVal)
+        def yajl_start_map(self, ctx):
+            self.out.write("map open '{'\n")
+        def yajl_map_key(self, ctx, stringVal):
+            self.out.write("key: '%s'\n" %stringVal)
+        def yajl_end_map(self, ctx):
+            self.out.write("map close '}'\n")
+        def yajl_start_array(self, ctx):
+            self.out.write("array open '['\n")
+        def yajl_end_array(self, ctx):
+            self.out.write("array close ']'\n")
+
+    # Create the parser
+    parser = YajlParser(ContentHandler())
+    # Parse JSON from stdin
+    parser.parse()
+
+Generating
+++++++++++
+.. code-block:: python
+
+    from yajl import *
+
+    g = YajlGen(beautify=False)
+    g.yajl_gen_map_open()
+    g.yajl_gen_string("a")
+    g.yajl_gen_array_open()
+    g.yajl_gen_null()
+    g.yajl_gen_bool(True)
+    g.yajl_gen_integer(1)
+    g.yajl_gen_double(2.0)
+    g.yajl_gen_number(str(3))
+
+    g.yajl_gen_get_buf()
+    # [Out]: '{"a":[null,true,1,2,3'
+
+    g.yajl_gen_string("b")
+    g.yajl_gen_array_close()
+    g.yajl_gen_map_close()
+
+    g.yajl_gen_get_buf()
+    # [Out]: ',"b"]}'
 
 Documentaion
 ------------
@@ -80,7 +146,7 @@ docstrings:
 .. toctree::
 
     yajl/index
- 
+
 Indices and tables
 ==================
 

yajl/yajl_parse.py

@@ -73,6 +73,10 @@ class YajlContentHandler(object):
     the :meth:`yajl_integer` & :meth:`yajl_double` callbacks will be ignored.
     For this reason none of these three methods are enforced by the Abstract
     Base Class
+
+    **Note** all methods must accept a param :obj:`ctx` as the first argument,
+    this is a yajl feature that is implemented in yajl-py but not very useful
+    in python.  see :meth:`YajlParser.parse` for more info on :obj:`ctx`.
     '''
     __metaclass__ = ABCMeta
     @abstractmethod
@@ -121,10 +125,16 @@ class YajlParser(object):
     '''
     def __init__(self, content_handler=None, allow_comments=True, check_utf8=True, buf_siz=65536):
         '''
-        `content_handler` an instance of a subclass of YajlContentHandler
-        `allow_comments` specifies whether comments are allowed in the document
-        `check_utf8` specifies whether utf8 charachters are allowed in the document
-        `buf_siz` the number of bytes to process from the input stream at a time
+        :type content_handler: :class:`YajlContentHandler`
+        :param content_handler: content handler instance hosting the
+            callbacks that will be called while parsing.
+        :type allow_comments: bool
+        :param allow_comments: if comments are allowed in the document
+        :type check_utf8: bool
+        :param check_utf8: if utf8 charachters are allowed in the document
+        :type buf_siz: int
+        :param buf_siz: number of bytes to process from the input stream
+            at a time (minimum 1)
         '''
         # input validation
         if buf_siz <= 0:
@@ -194,16 +204,13 @@ def dispatch(func, *args, **kwargs):
     def parse(self, f=sys.stdin, ctx=None):
         '''Function to parse a JSON stream.
 
-        Parameters:
-
-            * `f` - file stream to read from
-            * `ctx` - A ctypes pointer that will be passed to all 
-              callback functions as the first param
-
-        Raises an expception upon error or return value of 0
-        from callback functions. A callback function that
-        returns 0 should set internal variables to denote
-        why they cancelled the parsing.
+        :type f: file
+        :param f: stream to parse JSON from
+        :type ctx: ctypes.POINTER
+        :param ctx: passed to all callback functions as the first param this is
+         a feature of yajl, and not very useful in yajl-py since the context is
+         preserved using the content_handler instance.
+        :raises YajlError: When invalid JSON in input stream found
         '''
         if self.content_handler:
             self.content_handler.parse_start()