style(help): put human explanation for opts above automated infos

+ Mimic behavior of similar libraries (docopt, click) and tools.

Part of #361.

traitlets/config/configurable.py

@@ -253,6 +253,13 @@ def class_get_trait_help(cls, trait, inst=None, helptext=None):
             header = '%s=<%s>' % (header, trait.__class__.__name__)
         #header = "--%s.%s=<%s>" % (cls.__name__, trait.name, trait.__class__.__name__)
         lines.append(header)
+
+        if helptext is None:
+            helptext = trait.help
+        if helptext != '':
+            helptext = '\n'.join(wrap_paragraphs(helptext, 76))
+            lines.append(indent(helptext, 4))
+
         if inst is not None:
             lines.append(indent('Current: %r' % getattr(inst, trait.name), 4))
         else:
@@ -268,11 +275,6 @@ def class_get_trait_help(cls, trait, inst=None, helptext=None):
             # include Enum choices
             lines.append(indent('Choices: %r' % (trait.values,)))
 
-        if helptext is None:
-            helptext = trait.help
-        if helptext != '':
-            helptext = '\n'.join(wrap_paragraphs(helptext, 76))
-            lines.append(indent(helptext, 4))
         return '\n'.join(lines)
 
     @classmethod

traitlets/config/tests/test_configurable.py

@@ -35,20 +35,20 @@ class MyConfigurable(Configurable):
 mc_help=u"""MyConfigurable(Configurable) options
 ------------------------------------
 --MyConfigurable.a=<Integer>
-    Default: 1
     The integer a.
+    Default: 1
 --MyConfigurable.b=<Float>
-    Default: 1.0
-    The integer b."""
+    The integer b.
+    Default: 1.0"""
 
 mc_help_inst=u"""MyConfigurable(Configurable) options
 ------------------------------------
 --MyConfigurable.a=<Integer>
-    Current: 5
     The integer a.
+    Current: 5
 --MyConfigurable.b=<Float>
-    Current: 4.0
-    The integer b."""
+    The integer b.
+    Current: 4.0"""
 
 # On Python 3, the Integer trait is a synonym for Int
 if PY3:
@@ -71,8 +71,8 @@ class Bar(Foo):
 foo_help=u"""Foo(Configurable) options
 -------------------------
 --Foo.a=<Int>
-    Default: 0
     The integer a.
+    Default: 0
 --Foo.b=<Unicode>
     Default: 'nope'
 --Foo.fdict=<key-1>=<value-1>...
@@ -83,15 +83,15 @@ class Bar(Foo):
 bar_help=u"""Bar(Foo) options
 ----------------
 --Bar.a=<Int>
-    Default: 0
     The integer a.
+    Default: 0
 --Bar.bdict <key-1>=<value-1>...
     Default: {}
 --Bar.bset <set-item-1>...
     Default: set()
 --Bar.c=<Float>
-    Default: 0.0
     The string c.
+    Default: 0.0
 --Bar.fdict=<key-1>=<value-1>...
     Default: {}
 --Bar.flist=<list-item-1>...