[doc] cleanup & refactorings

docs/extension/docker.rst

@@ -0,0 +1,8 @@
+Docker Extension
+================
+
+.. todo:: The `bonobo-docker` package is at a very alpha stage, and things will change. This section is here to give a
+    brief overview but is neither complete nor definitive.
+
+Read the introduction: https://www.bonobo-project.org/with/docker
+

docs/extension/index.rst

@@ -0,0 +1,14 @@
+Extensions
+==========
+
+Extensions contains all things needed to work with a few popular third party tools.
+
+Most of them are available as optional extra dependencies, and the maturity stage of each may vary.
+
+.. toctree::
+    :maxdepth: 2
+
+    docker
+    jupyter
+    selenium
+    sqlalchemy

docs/extension/jupyter.rst

@@ -0,0 +1,41 @@
+Jupyter Extension
+=================
+
+There is a builtin plugin that integrates (somewhat minimallistically, for now) bonobo within jupyter notebooks, so
+you can read the execution status of a graph within a nice (ok, not so nice) html/javascript widget.
+
+See https://github.com/jupyter-widgets/widget-cookiecutter for the base template used.
+
+Installation
+::::::::::::
+
+Install `bonobo` with the **jupyter** extra::
+
+    pip install bonobo[jupyter]
+
+Install the jupyter extension::
+
+    jupyter nbextension enable --py --sys-prefix widgetsnbextension
+    jupyter nbextension enable --py --sys-prefix bonobo.ext.jupyter
+
+Development
+:::::::::::
+
+You should favor yarn over npm to install node packages. If you prefer to use npm, it's up to you to adapt the code.
+
+To install the widget for development, make sure you're using an editable install of bonobo (see install document)::
+
+    jupyter nbextension install --py --symlink --sys-prefix bonobo.ext.jupyter
+    jupyter nbextension enable --py --sys-prefix bonobo.ext.jupyter
+
+If you want to change the javascript, you should run webpack in watch mode in some terminal::
+
+    cd bonobo/ext/jupyter/js
+    yarn install
+    ./node_modules/.bin/webpack --watch
+
+To compile the widget into a distributable version (which gets packaged on PyPI when a release is made), just run
+webpack::
+
+    ./node_modules/.bin/webpack
+

docs/extension/selenium.rst

@@ -0,0 +1,42 @@
+Selenium Extension
+==================
+
+.. todo:: The `bonobo-selenium` package is at a very alpha stage, and things will change. This section is here to give a
+          brief overview but is neither complete nor definitive.
+
+
+Writing web crawlers with Bonobo and Selenium is easy.
+
+First, install **bonobo-selenium**:
+
+.. code-block:: shell-session
+
+    $ pip install bonobo-selenium
+
+The idea is to have one callable crawl one thing and delegate drill downs to callables further away in the chain.
+
+An example chain could be:
+
+.. graphviz::
+
+    digraph {
+        rankdir = LR;
+        login -> paginate -> list -> details -> "ExcelWriter(...)";
+    }
+
+Where each step would do the following:
+
+* `login()` is in charge to open an authenticated session in the browser.
+* `paginate()` open each page of a fictive list and pass it to next.
+* `list()` take every list item and yield it.
+* `details()` extract the data you're interested in.
+* ... and the writer saves it somewhere.
+
+Installation
+::::::::::::
+
+Overview
+::::::::
+
+Details
+:::::::

docs/extension/sqlalchemy.rst

@@ -0,0 +1,16 @@
+SQLAlchemy Extension
+====================
+
+.. todo:: The `bonobo-sqlalchemy` package is at a very alpha stage, and things will change. This section is here to
+          give a brief overview but is neither complete nor definitive.
+
+Read the introduction: https://www.bonobo-project.org/with/sqlalchemy
+
+Installation
+::::::::::::
+
+Overview
+::::::::
+
+Details
+:::::::