Write docs for constants in sugar3.graphics.style

The constants must be documented, because otherwise they are hidden
from the generated online documentation.

[changes arising from review comments and flake8 compliance]
Signed-off-by: James Cameron <quozl@laptop.org>

src/sugar3/graphics/style.py

@@ -16,12 +16,13 @@
 # Boston, MA 02111-1307, USA.
 
 '''
-The style module defines constants for spacing and sizing, as well as classes for 
+The style module defines constants for spacing and sizing, as well as
-Colors and Fonts. Text rendering is handled by Pango and colors are inputted by their
+classes for  Colors and Fonts. Text rendering is handled by Pango and
-HTML code (e.g. #FFFFFFFF)
+colors are inputted by their HTML code (e.g. #FFFFFFFF)
 
-All the constants are expressed in pixels. They are defined for the XO screen
+All the constants are expressed in pixels. They are defined for the XO
-and are usually adapted to different resolution by applying a zoom factor.
+screen and are usually adapted to different resolution by applying a
+zoom factor.
 '''
 
 import os
@@ -39,7 +40,7 @@ ELLIPSIZE_MODE_DEFAULT = Pango.EllipsizeMode.END
 
 def _compute_zoom_factor():
     '''
-    Calculates zoom factor based on size of screen. 
+    Calculates zoom factor based on size of screen.
     Returns double representing fraction of maximum possible screen size
     '''
     try:
@@ -53,8 +54,8 @@ def _compute_zoom_factor():
 
 class Font(object):
     '''
-    A font defines the style of how the text should be rendered. 
+    A font defines the style of how the text should be rendered.
-    
+
     Args:
         desc (str): a description of the Font object
     '''
@@ -76,11 +77,11 @@ class Font(object):
 
 class Color(object):
     '''
-    A Color object defines a specific color. 
+    A Color object defines a specific color.
 
     Args:
         color (str): String in the form #FFFFFF representing the color
-        
+
         alpha (double):  transparency of color
     '''
     def __init__(self, color, alpha=1.0):
@@ -115,9 +116,9 @@ class Color(object):
 
     def _html_to_rgb(self, html_color):
         '''
-        Converts and returns (r, g, b) tuple in float format from standard HTML format (#FFFFFF).
+        Converts and returns (r, g, b) tuple in float format from
-        Colors will be in range 0-1
+        standard HTML format (#FFFFFF).  Colors will be in range 0-1
-        
+
         Args:
             html_color (string): html string in the format #FFFFFF
         '''
@@ -136,10 +137,10 @@ class Color(object):
 
     def get_svg(self):
         '''
-        Returns HTML formatted color, unless the color is completely transparent, in
+        Returns HTML formatted color, unless the color is completely
-        which case returns "none"
+        transparent, in which case returns "none"
         '''
-        
+
         if self._a == 0.0:
             return 'none'
         else:
@@ -149,59 +150,89 @@ class Color(object):
 def zoom(units):
     '''
     Returns size of units pixels at current zoom level
-    
+
     Args:
         units (int): size of item at full size
     '''
     return int(ZOOM_FACTOR * units)
 
 
-ZOOM_FACTOR = _compute_zoom_factor()
+ZOOM_FACTOR = _compute_zoom_factor()  #: scale factor, as float (eg. 0.72, 1.0)
 
-DEFAULT_SPACING = zoom(15)
+DEFAULT_SPACING = zoom(15)  #: Spacing is placed in-between elements
-DEFAULT_PADDING = zoom(6)
+DEFAULT_PADDING = zoom(6)  #: Padding is placed around an element
+
+#: allow elements to tile neatly within boundaries of a grid
+#: http://wiki.sugarlabs.org/go/Human_Interface_Guidelines#The_Grid_System
 GRID_CELL_SIZE = zoom(75)
-LINE_WIDTH = zoom(2)
 
+LINE_WIDTH = zoom(2)  #: Thickness of a separator line
+
+#: icon that fits within a grid cell
 STANDARD_ICON_SIZE = zoom(55)
+#: small icon, used in palette menu items
 SMALL_ICON_SIZE = zoom(33)
+#: larger than standard
 MEDIUM_ICON_SIZE = zoom(55 * 1.5)
+#: larger than medium, used in journal empty view
 LARGE_ICON_SIZE = zoom(55 * 2.0)
+#: larger than large, used in activity pulsing launcher icon
 XLARGE_ICON_SIZE = zoom(55 * 2.75)
 
 if 'org.sugarlabs.font' in Gio.Settings.list_schemas():
     settings = Gio.Settings('org.sugarlabs.font')
+    #: User's preferred font size
     FONT_SIZE = settings.get_double('default-size')
+    #: User's preferred font face
     FONT_FACE = settings.get_string('default-face')
 else:
+    #: User's preferred font size
     FONT_SIZE = 10
-    FONT_FACE = 'Sans Serif' 
+    #: User's preferred font face
+    FONT_FACE = 'Sans Serif'
 
+#: Normal font
 FONT_NORMAL = Font('%s %f' % (FONT_FACE, FONT_SIZE))
+#: Bold font
 FONT_BOLD = Font('%s bold %f' % (FONT_FACE, FONT_SIZE))
+#: Height in pixels of normal font
 FONT_NORMAL_H = zoom(24)
+#: Height in pixels of bold font
 FONT_BOLD_H = zoom(24)
 
+# old style toolbox design
 TOOLBOX_SEPARATOR_HEIGHT = zoom(9)
 TOOLBOX_HORIZONTAL_PADDING = zoom(75)
 TOOLBOX_TAB_VBORDER = int((zoom(36) - FONT_NORMAL_H - FOCUS_LINE_WIDTH) / 2)
 TOOLBOX_TAB_HBORDER = zoom(15) - FOCUS_LINE_WIDTH - _TAB_CURVATURE
 TOOLBOX_TAB_LABEL_WIDTH = zoom(150 - 15 * 2)
 
-COLOR_BLACK = Color('#000000')
+COLOR_BLACK = Color('#000000')  #: Black
-COLOR_WHITE = Color('#FFFFFF')
+COLOR_WHITE = Color('#FFFFFF')  #: White
+#: Fully transparent color
 COLOR_TRANSPARENT = Color('#FFFFFF', alpha=0.0)
+#: Default background color of a window
 COLOR_PANEL_GREY = Color('#C0C0C0')
+#: Background color of selected entry
 COLOR_SELECTION_GREY = Color('#A6A6A6')
+#: Color of toolbars
 COLOR_TOOLBAR_GREY = Color('#282828')
+#: Color of buttons
 COLOR_BUTTON_GREY = Color('#808080')
+#: Fill colour of an inactive button
 COLOR_INACTIVE_FILL = Color('#9D9FA1')
+#: Stroke colour of an inactive button
 COLOR_INACTIVE_STROKE = Color('#757575')
+#: Background color of entry
 COLOR_TEXT_FIELD_GREY = Color('#E5E5E5')
+#: Color of highlighted text
 COLOR_HIGHLIGHT = Color('#E7E7E7')
 
+#: Cursor invoked palettes will be placed this far from the cursor
 PALETTE_CURSOR_DISTANCE = zoom(10)
 
+#: Size of arrow displayed under toolbar buttons to represent their status
 TOOLBAR_ARROW_SIZE = zoom(24)
 
+#: Max width of text in a palette menu, in chars
 MENU_WIDTH_CHARS = 60