Clean up novice __init__

Move functions from __init__ to novice module and clean up package docstring.
Doctest now passes.

skimage/novice/__init__.py

@@ -5,65 +5,69 @@ A special Python image submodule for beginners.
 
 Description
 -----------
-skimage.novice provides a simple image manipulation interface for beginners.
-It allows for easy loading, manipulating, and saving of image files.
+``skimage.novice`` provides a simple image manipulation interface for
+beginners.  It allows for easy loading, manipulating, and saving of image
+files.
+
+This module is primarily intended for teaching and differs significantly from
+the normal, array-oriented image functions used by scikit-image.
+
+.. note::
+
+    This module uses the Cartesian coordinate system, where the origin is at
+    the lower-left corner instead of the upper-right.
 
-NOTE: This module uses the Cartesian coordinate system!
 
 Example
 -------
 
-    >>> from skimage import novice            # special submodule for beginners
+We can create a Picture object open opening an image file
+>>> from skimage import novice
+>>> from skimage import data
+>>> picture = novice.open(data.data_dir + '/elephant.png')
+
+Pictures know their format
+>>> print picture.format
+png
+
+... and where they came from
+>>> print picture.path.endswith('elephant.png')
+True
+
+... and their size
+>>> print picture.size
+(665, 500)
+>>> print picture.width
+665
+
+Changing `size` resizes the picture.
+>>> picture.size = (200, 250)
+
+You can iterate over pixels, which have RGB values between 0 and 255,
+and know their location in the picture.
+>>> for pixel in picture:
+...     if (pixel.red > 128) and (pixel.x < picture.width):
+...         pixel.red /= 2
+
+Pictures know if they've been modified from the original file
+>>> print picture.modified
+True
+>>> print picture.path
+None
+
+Pictures can be indexed like arrays
+>>> picture[0:20, 0:20] = (0, 0, 0)
+
+Saving the picture updates the path attribute, format, and modified state.
+>>> picture.save('sample-bluegreen.jpg')
+>>> print picture.path.endswith('sample-bluegreen.jpg')
+True
+>>> print picture.format
+jpeg
+>>> print picture.modified
+False
 
-    >>> picture = novice.open('sample.png')   # create a picture object from a file
-    >>> print picture.format                  # pictures know their format...
-    'png'
-    >>> print picture.path                    # ...and where they came from...
-    '/Users/example/sample.png'
-    >>> print picture.size                    # ...and their size
-    (665, 500)
-    >>> print picture.width                   # 'width' and 'height' also exposed
-    665
-    >>> picture.size = (200, 250)             # changing size automatically resizes
-    >>> for pixel in picture:                 # can iterate over pixels
-    >>> ... if ((pixel.red > 128) and         # pixels have RGB (values are 0-255)...
-    >>> ...     (pixel.x < picture.width)):   # ...and know where they are
-    >>> ...     pixel.red /= 2                # pixel is an alias into the picture
-    >>> ...
-    >>> print picture.modified                # pictures know if their pixels are dirty
-    True
-    >>> print picture.path                    # picture no longer corresponds to file
-    None
-    >>> picture[0:20, 0:20] = (0, 0, 0)       # overwrite lower-left rectangle with black
-    >>> picture.save('sample-bluegreen.jpg')  # guess file type from suffix
-    >>> print picture.path                    # picture now corresponds to file
-    '/Users/example/sample-bluegreen.jpg'
-    >>> print picture.format                  # ...has a different format
-    jpeg
-    >>> print picture.modified                # and is now in sync
-    False
 """
 
-import os as _os
-from .colors import *
-from .novice import Picture
-
-def open(path):
-    """
-    Creates a new Picture object from the given image path
-    """
-    return Picture(path=_os.path.abspath(path))
-
-def new(size, color=None):
-    """
-    Create a new RGB picture of the given size, initialized to the
-    given color or to black if none is provided.
-    """
-    return Picture(size=size, color=color)
-
-def copy(image):
-    """
-    Creates a Picture using the supplied image data
-    (e.g., skimage.data.elephant()).
-    """
-    return Picture(image=image)
+from . import colors
+from .novice import Picture, open, new, copy

skimage/novice/novice.py

@@ -7,6 +7,27 @@ from skimage import img_as_ubyte
 from skimage.transform import resize
 
 
+def open(path):
+    """
+    Creates a new Picture object from the given image path
+    """
+    return Picture(path=os.path.abspath(path))
+
+def new(size, color=None):
+    """
+    Create a new RGB picture of the given size, initialized to the
+    given color or to black if none is provided.
+    """
+    return Picture(size=size, color=color)
+
+def copy(image):
+    """
+    Creates a Picture using the supplied image data
+    (e.g., skimage.data.elephant()).
+    """
+    return Picture(image=image)
+
+
 class Pixel(object):
     """A single pixel in a Picture.