add examples to documentation

docs/_templates/usefullinks.html

@@ -4,4 +4,5 @@ <h3>Useful links</h3>
     <li><a href="http://github.com/siddhantgoel/streaming-form-data">Github</a></li>
     <li><a href="http://github.com/siddhantgoel/streaming-form-data/issues">Issues @ Github</a></li>
     <li><a href="http://cython.org">Cython</a></li>
+    <li><a href="http://tornadoweb.org">Tornado</a></li>
 </ul>

docs/index.rst

@@ -9,36 +9,30 @@ Streaming multipart/form-data parser
 
 
 :code:`streaming_form_data` provides a Python parser for parsing
-:code:`multipart/form-data` input chunks. Chunk size is determined by the API
-user, but currently there are no restrictions on what the size should be, since
-the parser works byte-by-byte. This also means that passing the entire input as
-a single chunk should also work.
-
-The parser is fed chunks of (bytes) input, and takes action depending on what
-the current byte is. In case it notices input that's expected (input that has
-been registered by calling :code:`parser.register`, it will pass on the input to
-the registered :code:`Target` class which will then decide what to do with it.
-In case there's a part which is not needed, it can be associated to a
-:code:`NullTarget` object and it will be discarded.
+:code:`multipart/form-data` input chunks (the most commonly used encoding when
+submitting values through HTML forms). Chunk size is determined by the API user,
+but currently there are no restrictions on what the size should be, since the
+parser works byte-by-byte. This also means that passing the entire input as a
+single chunk should also work.
 
 Please note, that this library has only been tested with Python 3 (specifically,
 versions 3.3, 3.4, 3.5, and 3.6). Python 2.7 is not supported yet, but pull
-requests are always welcome.
+requests are always welcome. 🙂
 
 Installation
 ------------
 
+.. code-block:: bash
+
+    $ pip install streaming_form_data
+
 The core parser is written in :code:`Cython`, which is a superset of Python but
 compiles the input down to a C extension which can then be imported in normal
 Python code.
 
 The compiled C parser code is included in the PyPI package, hence the
 installation requires a working C compiler.
 
-.. code-block:: bash
-
-    $ pip install streaming_form_data
-
 Usage
 -----
 
@@ -57,6 +51,13 @@ Usage
     >>>
     >>> parser.data_received(chunk)
 
+The parser is fed chunks of (bytes) input, and takes action depending on what
+the current byte is. In case it notices input that's expected (input that has
+been registered by calling :code:`parser.register`, it will pass on the input to
+the registered :code:`Target` class which will then decide what to do with it.
+In case there's a part which is not needed, it can be associated to a
+:code:`NullTarget` object and it will be discarded.
+
 
 API
 ---
@@ -81,6 +82,17 @@ Any new targets should inherit :code:`streaming_form_data.targets.BaseTarget`
 and define a :code:`data_received` function.
 
 
+Examples
+--------
+
+Most of the testing has been done using the :code:`Tornado` web framework which
+allows reading HTTP request data as it arrives in chunks. If you'd like to
+document usage with another web framework (which ideally allows chunked reads),
+please open an issue or a pull request. 🙂
+
+- :code:`Tornado` - https://git.io/vHeqQ
+
+
 .. toctree::
    :maxdepth: 2
    :caption: Contents: