Merge branch 'master' into develop

bonobo/config/configurables.py

@@ -1,5 +1,5 @@
 from bonobo.errors import AbstractError
-from bonobo.util import isoption, iscontextprocessor, sortedlist
+from bonobo.util import isoption, iscontextprocessor, sortedlist, get_name
 
 __all__ = [
     'Configurable',
@@ -37,6 +37,26 @@ class ConfigurableMeta(type):
                     cls.__names.add(name)
                     cls.__options.insort((not value.positional, value._creation_counter, name, value))
 
+        # Docstring formating
+        _options_doc = []
+        for _positional, _counter, _name, _value in cls.__options:
+            _param = _name
+            if _value.type:
+                _param = get_name(_value.type) + ' ' + _param
+
+            prefix = ':param {}: '.format(_param)
+            for lineno, line in enumerate((_value.__doc__ or '').split('\n')):
+                _options_doc.append((' ' * len(prefix) if lineno else prefix) + line)
+        cls.__doc__ = '\n\n'.join(
+            map(
+                str.strip,
+                filter(None, (
+                    cls.__doc__,
+                    '\n'.join(_options_doc)
+                ))
+            )
+        )
+
     @property
     def __options__(cls):
         return ((name, option) for _, _, name, option in cls.__options)

bonobo/config/options.py

@@ -1,3 +1,4 @@
+import textwrap
 import types
 
 from bonobo.util.inspect import istype
@@ -62,7 +63,12 @@ class Option:
         self.positional = positional
         self.default = default
 
-        self.__doc__ = __doc__ or self.__doc__
+        # Docstring formating
+        self.__doc__ = __doc__ or None
+        if self.__doc__:
+            self.__doc__ = textwrap.dedent(self.__doc__.strip('\n')).strip()
+            if default:
+                self.__doc__ += '\nDefault: {!r}'.format(default)
 
         # This hack is necessary for python3.5
         self._creation_counter = Option._creation_counter

bonobo/nodes/io/base.py

@@ -12,12 +12,21 @@ class FileHandler(Configurable):
         encoding (str): which encoding to use when opening the file.
     """
 
-    path = Option(str, required=True, positional=True)  # type: str
-    eol = Option(str, default='\n')  # type: str
-    mode = Option(str)  # type: str
-    encoding = Option(str, default='utf-8')  # type: str
-
-    fs = Service('fs')  # type: str
+    path = Option(str, required=True, positional=True, __doc__='''
+        Path to use within the provided filesystem.
+    ''')  # type: str
+    eol = Option(str, default='\n', __doc__='''
+        Character to use as line separator.
+    ''')  # type: str
+    mode = Option(str, __doc__='''
+        What mode to use for open() call.
+    ''')  # type: str
+    encoding = Option(str, default='utf-8', __doc__='''
+        Encoding.
+    ''')  # type: str
+    fs = Service('fs', __doc__='''
+        The filesystem instance to use.
+    ''')  # type: str
 
     @ContextProcessor
     def file(self, context, *, fs):

bonobo/nodes/io/csv.py

@@ -55,14 +55,11 @@ class CsvHandler(FileHandler):
 class CsvReader(FileReader, CsvHandler):
     """
     Reads a CSV and yield the values as dicts.
-
-    .. attribute:: skip
-
-        The amount of lines to skip before it actually yield output.
-
     """
 
-    skip = Option(int, default=0)
+    skip = Option(int, default=0, __doc__='''
+        If set and greater than zero, the reader will skip this amount of lines.
+    ''')
 
     @Method(
         positional=False,

bonobo/nodes/io/file.py

@@ -12,7 +12,9 @@ class FileReader(Reader, FileHandler):
     present. Extending it is usually the right way to create more specific file readers (like json, csv, etc.)
     """
 
-    mode = Option(str, default='r')
+    mode = Option(str, default='r', __doc__='''
+        What mode to use for open() call.
+    ''')  # type: str
 
     output_fields = Option(
         ensure_tuple,
@@ -70,7 +72,9 @@ class FileWriter(Writer, FileHandler):
     usually the right way to create more specific file writers (like json, csv, etc.)
     """
 
-    mode = Option(str, default='w+')
+    mode = Option(str, default='w+', __doc__='''
+        What mode to use for open() call.
+    ''')  # type: str
 
     def write(self, file, context, line, *, fs):
         """

bonobo/structs/graphs.py

@@ -64,7 +64,7 @@ class Graph:
                     if _name in self.named:
                         raise KeyError('Duplicate name {!r} in graph.'.format(_name))
                     self.named[_name] = _last
-                if not _first:
+                if _first is None:
                     _first = _last
                 self.outputs_of(_input, create=True).add(_last)
                 _input = _last