From 8fc0430a233db7bf9606ed56295ea2f008128a66 Mon Sep 17 00:00:00 2001
From: Romain Dorgueil <romain@dorgueil.net>
Date: Mon, 1 May 2017 10:21:56 +0200
Subject: [PATCH] more documentage

---
 bonobo/examples/datasets/coffeeshops.py | 15 +++++++
 bonobo/examples/datasets/fablabs.py     | 16 +++++++
 bonobo/examples/utils/count.py          | 20 +++++++--
 docs/_static/graphs.css                 |  2 +-
 docs/reference/commands.rst             |  4 +-
 docs/reference/examples.rst             | 56 +++++++++++++++++++++----
 6 files changed, 100 insertions(+), 13 deletions(-)

diff --git a/bonobo/examples/datasets/coffeeshops.py b/bonobo/examples/datasets/coffeeshops.py
index 9c6e187..dc3db52 100644
--- a/bonobo/examples/datasets/coffeeshops.py
+++ b/bonobo/examples/datasets/coffeeshops.py
@@ -1,3 +1,18 @@
+"""
+Extracts a list of parisian bars where you can buy a coffee for a reasonable price, and store them in a flat text file.
+
+.. graphviz::
+
+    digraph {
+        rankdir = LR;
+        stylesheet = "../_static/graphs.css";
+
+        BEGIN [shape="point"];
+        BEGIN -> "ODS()" -> "transform" -> "FileWriter()";
+    }
+
+"""
+
 import bonobo
 from bonobo.commands.run import get_default_services
 from bonobo.ext.opendatasoft import OpenDataSoftAPI
diff --git a/bonobo/examples/datasets/fablabs.py b/bonobo/examples/datasets/fablabs.py
index 1ed52d7..17ee841 100644
--- a/bonobo/examples/datasets/fablabs.py
+++ b/bonobo/examples/datasets/fablabs.py
@@ -1,3 +1,19 @@
+"""
+Extracts a list of fablabs in the world, restrict to the ones in france, then format it both for a nice console output
+and a flat txt file.
+
+.. graphviz::
+
+    digraph {
+        rankdir = LR;
+        stylesheet = "../_static/graphs.css";
+
+        BEGIN [shape="point"];
+        BEGIN -> "ODS()" -> "normalize" -> "filter_france" -> "Tee()" -> "JsonWriter()";
+    }
+
+"""
+
 import json
 
 from colorama import Fore, Style
diff --git a/bonobo/examples/utils/count.py b/bonobo/examples/utils/count.py
index fdcc3bf..ea440a0 100644
--- a/bonobo/examples/utils/count.py
+++ b/bonobo/examples/utils/count.py
@@ -1,7 +1,21 @@
-import bonobo
-import bonobo.basics
+"""
+Simple example of :func:`bonobo.count` usage.
 
-graph = bonobo.Graph(range(42), bonobo.basics.count, print)
+.. graphviz::
+
+    digraph {
+        rankdir = LR;
+        stylesheet = "../_static/graphs.css";
+
+        BEGIN [shape="point"];
+        BEGIN -> "range()" -> "count" -> "print";
+    }
+
+"""
+
+import bonobo
+
+graph = bonobo.Graph(range(42), bonobo.count, print)
 
 if __name__ == '__main__':
     bonobo.run(graph)
diff --git a/docs/_static/graphs.css b/docs/_static/graphs.css
index 873f3d6..abed45c 100644
--- a/docs/_static/graphs.css
+++ b/docs/_static/graphs.css
@@ -1,2 +1,2 @@
 .node {
-}
\ No newline at end of file
+}
diff --git a/docs/reference/commands.rst b/docs/reference/commands.rst
index f7c95af..dcd054a 100644
--- a/docs/reference/commands.rst
+++ b/docs/reference/commands.rst
@@ -1,5 +1,5 @@
-Command-line Reference
-======================
+Command-line
+============
 
 Bonobo Init
 :::::::::::
diff --git a/docs/reference/examples.rst b/docs/reference/examples.rst
index bddbe8b..e2f922d 100644
--- a/docs/reference/examples.rst
+++ b/docs/reference/examples.rst
@@ -1,13 +1,44 @@
 Examples
 ========
 
-There are a few examples bundled with **bonobo**. You'll find them under the :mod:`bonobo.examples` package.
+There are a few examples bundled with **bonobo**. You'll find them under the :mod:`bonobo.examples` package, and
+you can try them in a clone of bonobo by typing::
+
+    $ bonobo run bonobo/examples/.../file.py
+
+
+Datasets
+::::::::
+
+
+.. module:: bonobo.examples.datasets
+
+The :mod:`bonobo.examples.datasets` package contains examples that generates datasets locally for other examples to
+use. As of today, we commit the content of those datasets to git, even if that may be a bad idea, so all the examples
+are easily runnable. Later, we'll see if we favor a "missing dependency exception" approach.
+
+
+Coffeeshops
+-----------
+
+.. automodule:: bonobo.examples.datasets.coffeeshops
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+Fablabs
+-------
+
+.. automodule:: bonobo.examples.datasets.fablabs
+    :members:
+    :undoc-members:
+    :show-inheritance:
 
 Types
 :::::
 
-bonobo.examples.types.strings
------------------------------
+Strings
+-------
 
 .. automodule:: bonobo.examples.types.strings
     :members: graph, extract, transform, load
@@ -15,8 +46,8 @@ bonobo.examples.types.strings
     :show-inheritance:
 
 
-bonobo.examples.types.dicts
----------------------------
+Dicts
+-----
 
 .. automodule:: bonobo.examples.types.dicts
     :members: graph, extract, transform, load
@@ -24,8 +55,8 @@ bonobo.examples.types.dicts
     :show-inheritance:
 
 
-bonobo.examples.types.bags
---------------------------
+Bags
+----
 
 .. automodule:: bonobo.examples.types.bags
     :members: graph, extract, transform, load
@@ -33,4 +64,15 @@ bonobo.examples.types.bags
     :show-inheritance:
 
 
+Utils
+:::::
+
+Count
+-----
+
+.. automodule:: bonobo.examples.utils.count
+    :members:
+    :undoc-members:
+    :show-inheritance:
+