separating docs in multiple files and improving quickstart

docs/Makefile

@@ -24,6 +24,7 @@ I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
 	@echo "  html       to make standalone HTML files"
+	@echo "  livehtml   to make rebuild on save"
 	@echo "  dirhtml    to make HTML files named index.html in directories"
 	@echo "  singlehtml to make a single large HTML file"
 	@echo "  pickle     to make pickle files"

docs/source/about.md

@@ -0,0 +1,8 @@
+# tapioca-wrapper
+
+**tapioca** provides an easy way to make explorable python API wrappers.
+APIs wrapped by Tapioca follow a simple interaction pattern that works uniformelly so developers don't need to learn how to use a new coding interface/style for each service API.
+
+Supports Python 2.7, 3.2, 3.3 and 3.4.
+
+![Tapioca!!](_static/tapioca.jpg "Tapioca")

docs/source/contributors.md

@@ -0,0 +1,4 @@
+# Contributors
+
+- André Ericson (<de.ericson@gmail.com>)
+- Filipe Ximenes (<filipeximenes@gmail.com>)

docs/source/flavours.md

@@ -0,0 +1,13 @@
+# Available Flavours
+
+## Facebook
+[https://github.com/vintasoftware/tapioca-facebook](https://github.com/vintasoftware/tapioca-facebook)
+## Twitter
+[https://github.com/vintasoftware/tapioca-twitter](https://github.com/vintasoftware/tapioca-twitter)
+## Mandrill
+[https://github.com/vintasoftware/tapioca-mandrill](https://github.com/vintasoftware/tapioca-mandrill)
+## Parse
+[https://github.com/vintasoftware/tapioca-parse](https://github.com/vintasoftware/tapioca-parse)
+
+### Your flavour
+Send a pull request to add new ones to the list.

docs/source/index.rst

@@ -3,12 +3,16 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to tapioca-wrapper's documentation!
+Welcome to tapioca-wrapper documentation!
 ===========================================
 
 Contents:
 
 .. toctree::
    :maxdepth: 2
 
+   about
    quickstart
+   newflavour
+   flavours
+   contributors

docs/source/newflavour.md

@@ -0,0 +1,45 @@
+# Wrapping an API with Tapioca
+
+This is all the code you need to build the Facebook Graph API wrapper you just played with:
+``` python
+# source here: https://github.com/vintasoftware/tapioca-facebook/blob/master/tapioca_facebook/tapioca_facebook.py
+
+from tapioca import (
+    TapiocaAdapter, generate_wrapper_from_adapter)
+from requests_oauthlib import OAuth2
+
+from resource_mapping import RESOURCE_MAPPING
+
+
+class FacebookClientAdapter(TapiocaAdapter):
+    api_root = 'https://graph.facebook.com'
+    resource_mapping = RESOURCE_MAPPING
+
+    def get_request_kwargs(self, api_params):
+        client_id = api_params.get('client_id')
+        return {
+            'auth': OAuth2(client_id,
+                token={
+                    'access_token': api_params.get('access_token'),
+                    'token_type': 'Bearer'})
+        }
+
+    def get_iterator_list(self, response_data):
+        return response_data['data']
+
+    def get_iterator_next_request_kwargs(self,
+            iterator_request_kwargs, response_data):
+        paging = response_data.get('paging')
+        if not paging:
+            return
+        url = paging.get('next')
+
+        if url:
+            return {'url': url}
+
+
+Facebook = generate_wrapper_from_adapter(FacebookClientAdapter)
+```
+Everything else is what we call ```resource_mapping``` and its merely documentation. You can take a look  [here](https://github.com/vintasoftware/tapioca-facebook/blob/master/tapioca_facebook/resource_mapping.py).
+
+**don't forget to add your new flavour to the [list](flavours.md)**

docs/source/quickstart.md

@@ -1,34 +1,35 @@
-# Tapioca-Wrapper
+# Using a tapioca package
 
-![Tapioca!!](tapioca.jpg "Tapioca")
+**Yes, you are in the right place**
 
-Tapioca provides an easy way to make explorable python API wrappers.
-APIs wrapped by Tapioca follow a simple interaction pattern that works uniformelly so developers don't need to learn how to use a new coding interface/style for each service API.
+There is a good chance you found this page because you clicked a link from some python package called **tapioca-*SOMETHING***. Well, welcome! You are in the right place, this page will teach you the basics of how to use the package that sent you here. If you didn't arive here from other package, please keep reading, the concepts learned here applies to any tapioca-***package*** available.
 
-Supports Python 2.7, 3.2, 3.3 and 3.4.
+## What's tapioca?
 
-## Concepts
+**tapioca** is a *API wrapper maker*. It helps Python developers creating packages for APIs (like the [Facebook Graph API](flavours.html#facebook) or the [Twitter REST API](flavours.html#twitter)). You can find a full list of available API packages made with tapioca [here](flavours.md).  
+
+All wrappers made with tapioca follow a simple interaction pattern that works uniformelly so once you learn how tapioca works you will be able to work with any tapioca package available.
 
-Uniform and explorable wrappers means developers don't need to read full API and wrapper documentation before starting to play with it.
+## Concepts
 
-We will use ```tapioca-facebook``` as example to gide us through Tapioca.
-We start by installing ```tapioca-facebook```:
+We will use ```tapioca-facebook``` as example to gide us through tapioca concepts.
+Lets install ```tapioca-facebook```:
 ```
 pip install tapioca-facebook
 ```
 
-To better experience Tapioca, we will also use iPython:
+To better experience tapioca, we will also use iPython:
 ```
 pip install ipython
 ```
 
-Now, lets explore!!
+Lets explore!!
 Go to [https://developers.facebook.com/tools/explorer/](https://developers.facebook.com/tools/explorer/), click "Get Access Token", select all "User Data Permissions" and "Extended Permissions" and click "Get Access Token". This will give you an teporary access token to play with Facebook API. In case it expires, just generate a new one.
 
 ``` python
 from tapioca_facebook import Facebook
 
-api = Facebook(access_token='{your_genereated_access_token}')
+api = Facebook(access_token='your_genereated_access_token')
 
 ```
 
@@ -94,31 +95,39 @@ likes.data    likes.paging
 
 ### Executor object
 
-Whenever you use brackets, Tapioca will return to you an ```Executor``` object. You will use the executor every time you want to perform an action over data you possess. An example was when we filled url params for the ```user_likes``` resource, and then used the ```get``` method to fetch data.
+Whenever you use brackets, Tapioca will return to you an ```Executor``` object. You will use the executor every time you want to perform an action over data you possess. 
+
+An example was when we filled url params for the ```user_likes``` resource (calling it and passign the argument ``id='me'``). Whenever you make a ``call`` from a ``TapiocaClient`` it will return a ``TapiocaClientExecutor`` object. In this new object you will find many methods to help you play with the data available.
 
-Tapioca provides many methods, here are they:
+Here is the list of the methods available in a ``TapiocaClientExecutor``:
 
 #### get()/post()/put()/delete()/head()/options()
 
-Tapioca uses ```requests``` library to make requests, so http methods will work just the same.
+Tapioca uses [requests](http://docs.python-requests.org/en/latest/) library to make requests, so http methods will work just the same. 
 ``` python
 likes = api.user_likes(id='me').get()
 ```
+Please read [requests](http://docs.python-requests.org/en/latest/) for more detailed information about tho use HTTP methods. 
 
 #### data()
 Use data to return data contained in the Tapioca object
 ``` python
-likes = api.user_likes(id='me').get()
-
-# this will print only the array contained in data field of the response
-print(likes.data().data())
-[...]
+IN [8]: likes = api.user_likes(id='me').get()
+IN [9]: likes().data()
+OUT [10]: {
+    'data': [...],
+    'paging': {...}
+}
+# this will print only the array contained 
+# in the 'data' field of the response
+IN [11]: likes.data().data()
+OUT [12]: [...]
 ```
 
 #### iterator
 
 Many APIs use paging concept to provide large amounts of data. This way data is returned in multiple requests avoing a single long request.
-Tapioca is buit to provide easy way to access paged data using iterators:
+tapioca is buit to provide easy way to access paged data using iterators:
 
 ``` python
 likes = api.user_likes(id='me').get()
@@ -139,64 +148,3 @@ api.user_likes().open_docs()
 #### open_in_browser()
 
 Whenever the data contained in Tapioca object is a URL, you can open it in browser by using the ```open_in_browser``` method.
-
-
-## Tapioca comes in many flavours
-
-Facebook - [https://github.com/vintasoftware/tapioca-facebook](https://github.com/vintasoftware/tapioca-facebook)
-Twitter - [https://github.com/vintasoftware/tapioca-twitter](https://github.com/vintasoftware/tapioca-twitter)
-Mandrill - [https://github.com/vintasoftware/tapioca-mandrill](https://github.com/vintasoftware/tapioca-mandrill)
-Parse - [https://github.com/vintasoftware/tapioca-parse](https://github.com/vintasoftware/tapioca-parse)
-
-Send a pull request to add new ones to the list.
-
-## Wrapping an API with Tapioca
-
-This is all the code you need to build the Facebook Graph API wrapper you just played with:
-``` python
-# source here: https://github.com/vintasoftware/tapioca-facebook/blob/master/tapioca_facebook/tapioca_facebook.py
-
-from tapioca import (
-    TapiocaAdapter, generate_wrapper_from_adapter)
-from requests_oauthlib import OAuth2
-
-from resource_mapping import RESOURCE_MAPPING
-
-
-class FacebookClientAdapter(TapiocaAdapter):
-    api_root = 'https://graph.facebook.com'
-    resource_mapping = RESOURCE_MAPPING
-
-    def get_request_kwargs(self, api_params):
-        client_id = api_params.get('client_id')
-        return {
-            'auth': OAuth2(client_id,
-                token={
-                    'access_token': api_params.get('access_token'),
-                    'token_type': 'Bearer'})
-        }
-
-    def get_iterator_list(self, response_data):
-        return response_data['data']
-
-    def get_iterator_next_request_kwargs(self,
-            iterator_request_kwargs, response_data):
-        paging = response_data.get('paging')
-        if not paging:
-            return
-        url = paging.get('next')
-
-        if url:
-            return {'url': url}
-
-
-Facebook = generate_wrapper_from_adapter(FacebookClientAdapter)
-```
-Everything else is what we call ```resource_mapping``` and its merely documentation. You can take a look  [here](https://github.com/vintasoftware/tapioca-facebook/blob/master/tapioca_facebook/resource_mapping.py).
-
-## Contributors
-
-André Ericson de.ericson@gmail.com
-
-Filipe Ximenes filipeximenes@gmail.com
-