Merge pazz/sphinx

--HG--
branch : feature-sphinx

3 files changed, 91 insertions, 61 deletions

diff --git a/urwid/decoration.py b/urwid/decoration.py
index 14bb433..b2d6cad 100755
--- a/urwid/decoration.py
+++ b/urwid/decoration.py
@@ -104,17 +104,22 @@ class AttrMapError(WidgetError):
 
 class AttrMap(delegate_to_widget_mixin('_original_widget'), WidgetDecoration):
     """
-    AttrMap is a decoration that maps one set of attributes to another
+    AttrMap is a decoration that maps one set of attributes to another.
+    This object will pass all function calls and variable references to the
+    wrapped widget.
     """
     def __init__(self, w, attr_map, focus_map=None):
         """
-        w -- widget to wrap (stored as self.original_widget)
-        attr_map -- attribute to apply to w, or dictionary of attribute mappings
-        focus_map -- attribute to apply when in focus or dictionary of
-            attribute mappings, if None use attr
+        :param w: widget to wrap (stored as self.original_widget)
+        :type w: urwid.Widget
 
-        This object will pass all function calls and variable references
-        to the wrapped widget.
+        :param attr_map: attribute to apply to w, or dictionary of attribute
+            mappings
+        :type attr_map: urwid.AttrSpec or dict
+
+        :param focus_map: attribute to apply when in focus or dictionary of
+            attribute mappings, if None use attr
+        :type focus_map: urwid.AttrSpec or dict
 
         >>> AttrMap(Divider(u"!"), 'bright')
         <AttrMap flow widget <Divider flow widget '!'> attr_map={None: 'bright'}>
@@ -410,20 +415,28 @@ class Padding(WidgetDecoration):
     def __init__(self, w, align=LEFT, width=RELATIVE_100, min_width=None,
             left=0, right=0):
         """
-        w -- a box, flow or fixed widget to pad on the left and/or right
+        :param w: a box, flow or fixed widget to pad on the left and/or right
             this widget is stored as self.original_widget
-        align -- one of:
-            'left', 'center', 'right'
+        :type w: urwid.Widget
+
+        :param align: one of: 'left', 'center', 'right'
             ('relative', percentage 0=left 100=right)
-        width -- one of:
+
+        :param width: one of:
             fixed number of columns for self.original_widget
             'pack'   try to pack self.original_widget to its ideal size
             ('relative', percentage of total width)
             'clip'   to enable clipping mode for a fixed widget
-        min_width -- the minimum number of columns for
+
+        :param min_width: the minimum number of columns for
             self.original_widget or None
-        left -- a fixed number of columns to pad on the left
-        right -- a fixed number of columns to pad on thr right
+        :type min_width: int
+
+        :param left: a fixed number of columns to pad on the left
+        :type left: int
+
+        :param right: a fixed number of columns to pad on thr right
+        :type right: int
 
         Clipping Mode: (width='clip')
         In clipping mode this padding widget will behave as a flow
@@ -659,20 +672,27 @@ class Filler(WidgetDecoration):
     def __init__(self, body, valign=MIDDLE, height=FLOW, min_height=None,
             top=0, bottom=0):
         """
-        body -- a flow widget or box widget to be filled around (stored
+        :param body: a flow widget or box widget to be filled around (stored
             as self.original_widget)
-        valign -- one of:
-            'top', 'middle', 'bottom'
+        :type body: urwid.Widget
+
+        :param valign: one of:
+            'top', 'middle', 'bottom', 
             ('relative', percentage 0=top 100=bottom)
-        height -- one of:
+
+        :param height: one of:
             'flow'  if body is a flow widget
-            number of rows high
+            number of rows high, 
             ('relative', percentage of total height)
-        min_height -- one of:
-            None if no minimum or if body is a flow widget
+
+        :param min_height: one of:
+            `None` if no minimum or if body is a flow widget
             minimum number of rows for the widget when height not fixed
-        top -- a fixed number of rows to fill at the top
-        bottom -- a fixed number of rows to fill at the bottom
+
+        :param top: a fixed number of rows to fill at the top
+        :type top: int
+        :param bottom: a fixed number of rows to fill at the bottom
+        :type bottom: int
 
         If body is a flow widget then height must be 'flow' and and
         min_height will be ignored.
diff --git a/urwid/main_loop.py b/urwid/main_loop.py
index f961d2f..a3026cd 100755
--- a/urwid/main_loop.py
+++ b/urwid/main_loop.py
@@ -48,44 +48,47 @@ class MainLoop(object):
     """
     This is the standard main loop implementation with a single screen.
     """
+
+    screen = property
+    """The screen object this main loop uses for screen updates and reading
+    input"""
+
+    event_loop = property
+    """The event loop object this main loop uses for waiting on timers and IO"""
+
     def __init__(self, widget, palette=[], screen=None, 
             handle_mouse=True, input_filter=None, unhandled_input=None,
             event_loop=None, pop_ups=False):
         """
-        *widget* -- the topmost widget used for painting the screen, stored as
-        :attr:`.widget` and may be modified. Must be a box widget.
-
-        *palette* -- initial palette for screen.
-
-        *screen* -- screen object or ``None`` to use a new
-        :class:`urwid.raw_display.Screen` instance. stored as :attr:`.screen`
-
-        *handle_mouse* -- ``True`` to process mouse events, passed to
-        :attr:`.screen`
-
-        *input_filter* -- a function to filter input before sending it to
-        :attr:`.widget`, called from :meth:`.input_filter`
-
-        *unhandled_input* -- a function called when input is not handled by
-        :attr:`.widget`, called from :meth:`.unhandled_input`
+        :param widget: the topmost widget used for painting the screen, stored as
+                       :attr:`.widget` and may be modified. Must be a box widget.
+        :type widget: :class:`Widget`
 
-        *event_loop* -- if screen supports external an event loop it may be
-        given here, or leave as None to use a new
-        *SelectEventLoop* instance; stored as :attr:`.event_loop`
+        :param palette: initial palette for screen.
+        :type palette: list
 
-        *pop_ups* -- ``True`` to wrap :attr:`.widget` with a :class:`PopUpTarget`
-        instance to allow any widget to open a pop-up anywhere on the screen
+        :param screen: screen to use; stored as :attr:`screen`
+        :type screen: :class:`urwid.raw_display.Screen` or `None`
 
+        :param handle_mouse: `True` to process mouse events, passed to :attr:`.screen`
+        :type handle_mouse: boolean
 
-        .. attribute:: screen
+        :param input_filter: a function to filter input before sending it to
+                       :attr:`.widget`, called from :meth:`.input_filter`
+        :type input_filter: callable
 
-           The screen object this main loop uses for screen updates and reading
-           input
+        :param unhandled_input: a function called when input is not handled by
+                                :attr:`.widget`, called from :meth:`.unhandled_input`
+        :type unhandled_input: callable
 
-        .. attribute:: event_loop
+        :param event_loop: if :attr:`.screen` supports external an event loop it may be
+                           given here, or leave as None to use a new
+                           :class:`SelectEventLoop` instance; stored as :attr:`.event_loop`
+        :type event_loop: :class:`EventLoop`
 
-           The event loop object this main loop uses for waiting on timers
-           and IO
+        :param pop_ups: `True` to wrap :attr:`.widget` with a :class:`PopUpTarget`
+                        instance to allow any widget to open a pop-up anywhere on the screen
+        :type pop_ups: boolean
         """
         self._widget = widget
         self.handle_mouse = handle_mouse
@@ -1003,9 +1006,11 @@ if not PYTHON3:
 
         def __init__(self, reactor=None, manage_reactor=True):
             """
-            *reactor* -- reactor object to use, if ``None`` defaults to
-            ``twisted.internet.reactor``.  *manage_reactor* -- ``True`` if you want
-            this event loop to run and stop the reactor.
+            :param reactor: reactor to use
+            :type reactor: :class:`twisted.internet.reactor`.
+            :param: manage_reactor: `True` if you want this event loop to run
+                                    and stop the reactor.
+            :type manage_reactor: boolean
 
             .. WARNING::
                Twisted's reactor doesn't like to be stopped and run again.  If you
diff --git a/urwid/widget.py b/urwid/widget.py
index 4d8ad73..94b7664 100644
--- a/urwid/widget.py
+++ b/urwid/widget.py
@@ -611,11 +611,14 @@ class Divider(Widget):
 
     def __init__(self,div_char=u" ",top=0,bottom=0):
         """
-        Create a horizontal divider widget.
+        :param div_char: character to repeat across line
+        :type div_char: string
 
-        div_char -- character to repeat across line
-        top -- number of blank lines above
-        bottom -- number of blank lines below
+        :param top: number of blank lines above
+        :type top: int
+
+        :param bottom:number of blank lines below
+        :type bottom: int
 
         >>> Divider()
         <Divider flow widget>
@@ -671,15 +674,17 @@ class Divider(Widget):
 
 
 class SolidFill(BoxWidget):
+    """
+    A box widget that fills an area with a single character
+    """
     _selectable = False
     ignore_focus = True
 
     def __init__(self, fill_char=" "):
         """
-        Create a box widget that will fill an area with a single 
-        character.
-
-        fill_char -- character to fill area with
+        :param fill_char: character to fill area with
+        :type fill_char: string
+        """
 
         >>> SolidFill(u'8')
         <SolidFill box widget '8'>