more documentage

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

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

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)

docs/reference/commands.rst

@@ -1,5 +1,5 @@
-Command-line Reference
+Command-line
-======================
+============
 
 Bonobo Init
 :::::::::::

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:
+