[doc] proofreading the guides, refactoring the reference.

bonobo/_api.py

@@ -1,8 +1,16 @@
+"""
+Contains all the tools you need to get started with the framework, including (but not limited to) generic
+transformations, readers, writers, and tools for writing and executing graphs and jobs.
+
+All objects in this module are considered very safe to use, and backward compatibility when moving up from one version
+to another is maximal.
+
+"""
+
 from bonobo.execution.strategies import create_strategy
 from bonobo.nodes import __all__ as _all_nodes
 from bonobo.nodes import *
 from bonobo.structs import Graph
-from bonobo.util import get_name
 from bonobo.util.api import ApiHelper
 from bonobo.util.environ import parse_args, get_argument_parser
 
@@ -96,7 +104,8 @@ api.register_group(create_strategy)
 @api.register
 def open_fs(fs_url=None, *args, **kwargs):
     """
-    Wraps :func:`fs.open_fs` function with a few candies.
+    Wraps :obj:`fs.opener.registry.Registry.open_fs`, with default to local current working directory and expanding ~ in
+    path.
 
     :param str fs_url: A filesystem URL
     :param parse_result: A parsed filesystem URL.
@@ -105,9 +114,9 @@ def open_fs(fs_url=None, *args, **kwargs):
     :param bool create: True if the filesystem should be created if it does not exist.
     :param str cwd: The current working directory (generally only relevant for OS filesystems).
     :param str default_protocol: The protocol to use if one is not supplied in the FS URL (defaults to ``"osfs"``).
-    :returns: :class:`~fs.base.FS` object
+    :returns: :class:`fs.base.FS` object
     """
-    from fs import open_fs as _open_fs
+    from fs.opener import open_fs as _open_fs
     from os.path import expanduser
     from os import getcwd
 

bonobo/config/__init__.py

@@ -1,3 +1,9 @@
+"""
+The Config API, located under the :mod:`bonobo.config` namespace, contains all the tools you need to create
+configurable transformations, either class-based or function-based.
+
+"""
+
 from bonobo.config.configurables import Configurable
 from bonobo.config.functools import transformation_factory
 from bonobo.config.options import Method, Option

bonobo/config/options.py

@@ -68,7 +68,7 @@ class Option:
         if self.__doc__:
             self.__doc__ = textwrap.dedent(self.__doc__.strip('\n')).strip()
             if default:
-                self.__doc__ += '\nDefault: {!r}'.format(default)
+                self.__doc__ += '\n\nDefault: {!r}'.format(default)
 
         # This hack is necessary for python3.5
         self._creation_counter = Option._creation_counter

bonobo/constants.py

@@ -1,6 +1,28 @@
-class Token:
-    """Factory for signal oriented queue messages or other token types."""
+"""
+.. data:: BEGIN
 
+    **BEGIN** token marks the entrypoint of graphs, and all extractors will be connected to this node.
+
+    Without this, it would be impossible for an execution to actually start anything, as it's the marker that tells
+    |bonobo| which node to actually call when the execution starts.
+
+.. data:: NOT_MODIFIED
+
+    **NOT_MODIFIED** is a special value you can return or yield from a transformation to tell bonobo to reuse
+    the input data as output.
+
+    As a convention, all loaders should return this, so loaders can be chained.
+
+.. data:: EMPTY
+
+    Shortcut for "empty tuple". It's often much more clear to write (especially in a test) `write(EMPTY)` than
+    `write(())`, although strictly equivalent.
+
+
+"""
+
+
+class Token:
     def __init__(self, name):
         self.__name__ = name
 
@@ -8,16 +30,15 @@ class Token:
         return '<{}>'.format(self.__name__)
 
 
-BEGIN = Token('Begin')
-END = Token('End')
-
-
 class Flag(Token):
     must_be_first = False
     must_be_last = False
     allows_data = True
 
 
+BEGIN = Token('Begin')
+END = Token('End')
+
 INHERIT = Flag('Inherit')
 NOT_MODIFIED = Flag('NotModified')
 NOT_MODIFIED.must_be_first = True

bonobo/contrib/django/__init__.py

@@ -1,3 +1,11 @@
+"""
+This module contains all tools for Bonobo and Django to interract nicely.
+
+* :class:`ETLCommand`
+* :func:`create_or_update`
+
+"""
+
 from .utils import create_or_update
 from .commands import ETLCommand
 

bonobo/contrib/django/commands.py

@@ -26,6 +26,12 @@ class ETLCommand(BaseCommand):
     def create_parser(self, prog_name, subcommand):
         return bonobo.get_argument_parser(super().create_parser(prog_name, subcommand))
 
+    def add_arguments(self, parser):
+        """
+        Entry point for subclassed commands to add custom arguments.
+        """
+        pass
+
     def get_graph(self, *args, **options):
         def not_implemented():
             raise NotImplementedError('You must implement {}.get_graph() method.'.format(self))

bonobo/execution/__init__.py

@@ -1,3 +1,10 @@
+"""
+Execution logic, surrounding contexts for nodes and graphs and events.
+
+This module is considered **internal**.
+
+"""
+
 import logging
 
 logger = logging.getLogger(__name__)

bonobo/execution/contexts/__init__.py

@@ -1,3 +1,10 @@
+"""
+Execution Contexts are objects that wraps the stateless data-structures (graphs and nodes) during a job execution to
+keep an eye on their context/state (from the simplest things like i/o statistics to lifecycle and custom userland
+state).
+
+"""
+
 from bonobo.execution.contexts.graph import GraphExecutionContext
 from bonobo.execution.contexts.node import NodeExecutionContext
 from bonobo.execution.contexts.plugin import PluginExecutionContext

bonobo/execution/events.py

@@ -1,3 +1,30 @@
+"""
+.. data:: START
+
+    Event dispatched before execution starts.
+
+.. data:: STARTED
+
+    Event dispatched after execution starts.
+
+.. data:: TICK
+
+    Event dispatched while execution runs, on a regular basis (on each "tick").
+
+.. data:: STOP
+
+    Event dispatched before execution stops.
+
+.. data:: STOPPED
+
+    Event dispatched after execution stops.
+
+.. data:: KILL
+
+    Event dispatched when execution is killed.
+
+"""
+
 from whistle import Event
 
 START = 'execution.start'

bonobo/execution/strategies/__init__.py

@@ -1,3 +1,11 @@
+"""
+Execution strategies define how an actual job execution will happen. Default and recommended strategy is "threadpool",
+for now, which leverage a :obj:`concurrent.futures.ThreadPoolExecutor` to run each node in a separate thread.
+
+In the future, the two strategies that would really benefit bonobo are subprocess and dask/dask.distributed. Please be
+at home if you want to give it a shot.
+
+"""
 from bonobo.execution.strategies.executor import ProcessPoolExecutorStrategy, ThreadPoolExecutorStrategy
 from bonobo.execution.strategies.naive import NaiveStrategy
 

bonobo/util/__init__.py

@@ -1,3 +1,8 @@
+"""
+The Util API, located under the :mod:`bonobo.util` namespace, contains helpers functions and decorators to work with
+and inspect transformations, graphs, and nodes.
+
+"""
 from bonobo.util.collections import cast, ensure_tuple, sortedlist, tuplize
 from bonobo.util.compat import deprecated, deprecated_alias
 from bonobo.util.inspect import (