[doc] proofreading the guides, refactoring the reference.

docs/extension/django.rst

@@ -1,15 +1,16 @@
+.. currentmodule:: bonobo.contrib.django
+
 Working with Django
 ===================
 
-|bonobo| provides a lightweight integration with django, to allow to write management commands using |bonobo| graphs.
+|bonobo| provides a lightweight integration with django, to allow to include ETL pipelines in your django management
+commands.
 
-Management Command
-::::::::::::::::::
+Quick start
+:::::::::::
 
-To write a management command with |bonobo|, just extend the :class:`bonobo.contrib.django.ETLCommand` class and
-override the `get_graph()` method.
-
-Example:
+To write a django management command that runs |bonobo| job(s), just extend :class:`ETLCommand`
+instead of :class:`django.core.management.base.BaseCommand`, and override the :meth:`ETLCommand.get_graph` method:
 
 .. code-block:: python
 
@@ -22,7 +23,10 @@ Example:
             graph.add_chain(...)
             return graph
 
-You can also override the `get_services()` method.
+Services
+--------
+
+You can override :meth:`ETLCommand.get_services` to provide your service implementations.
 
 One common recipe to do so is to import it from somewhere else and override it as a :obj:`staticmethod`:
 
@@ -39,15 +43,51 @@ One common recipe to do so is to import it from somewhere else and override it a
         def get_graph(...):
             ...
 
+
+Multiple graphs
+---------------
+
+The :meth:`ETLCommand.get_graph` method can also be implemented as a generator. In this case, each element yielded must
+be a graph, and each graph will be executed in order:
+
+.. code-block:: python
+
+    import bonobo
+    from bonobo.contrib.django import ETLCommand
+
+    class Command(ETLCommand):
+        def get_graph(self, **options):
+            yield bonobo.Graph(...)
+            yield bonobo.Graph(...)
+            yield bonobo.Graph(...)
+
+This is especially helpful in two major cases:
+
+* You must ensure that one job is finished before the next is run, and thus you can't add both graph's nodes in the
+  same graph.
+* You want to change which graph is run depending on command line arguments.
+
+
+Command line arguments
+----------------------
+
+Like with regular django management commands, you can add arguments to the argument parser by overriding
+:meth:`ETLCommand.add_arguments`.
+
+The only difference with django is that the provided argument parser will already have arguments added to handle
+environment.
+
+
+Reference
+:::::::::
+
+:mod:`bonobo.contrib.django`
+----------------------------
+
+.. automodule:: bonobo.contrib.django
+
 Source code
 :::::::::::
 
 https://github.com/python-bonobo/bonobo/tree/master/bonobo/contrib/django
 
-Reference
-:::::::::
-
-.. automodule:: bonobo.contrib.django
-    :members:
-    :undoc-members:
-    :show-inheritance:

docs/extension/sqlalchemy.rst

@@ -1,5 +1,7 @@
-Working with SQL Databases
-==========================
+.. currentmodule:: bonobo_sqlalchemy
+
+Working with SQLAlchemy
+=======================
 
 .. include:: _beta.rst
 
@@ -54,6 +56,7 @@ Let's select some data:
 
 And let's insert some data:
 
+
 .. code-block:: python
 
     import bonobo
@@ -69,21 +72,13 @@ And let's insert some data:
 
         return graph
 
-
 Reference
 :::::::::
 
-.. module:: bonobo_sqlalchemy
+:mod:`bonobo_sqlalchemy`
+------------------------
 
-Select
-------
-
-.. autoclass:: Select
-
-InsertOrUpdate
---------------
-
-.. autoclass:: InsertOrUpdate
+.. automodule:: bonobo_sqlalchemy
 
 Source code
 :::::::::::