Fully document PIL.ImageColor

PIL/ImageColor.py

@@ -30,6 +30,15 @@ import re
 #    as an RGB value.
 
 def getrgb(color):
+    """
+     Convert a color string to an RGB tuple. If the string cannot be parsed,
+     this function raises a :py:exc:`ValueError` exception.
+
+    .. versionadded:: 1.1.4
+
+    :param color: A color string
+    :return: ``(red, green, blue)``
+    """
     try:
         rgb = colormap[color]
     except KeyError:
@@ -97,6 +106,16 @@ def getrgb(color):
     raise ValueError("unknown color specifier: %r" % color)
 
 def getcolor(color, mode):
+    """
+    Same as :py:func:`~PIL.ImageColor.getrgb`, but converts the RGB value to a
+    greyscale value if the mode is not color or a palette image. If the string
+    cannot be parsed, this function raises a :py:exc:`ValueError` exception.
+
+    .. versionadded:: 1.1.4
+
+    :param color: A color string
+    :return: ``(red, green, blue)``
+    """
     # same as getrgb, but converts the result to the given mode
     color = getrgb(color)
     if mode == "RGB":

docs/PIL.rst

@@ -65,14 +65,6 @@ PIL Package
     :undoc-members:
     :show-inheritance:
 
-:mod:`ImageColor` Module
-------------------------
-
-.. automodule:: PIL.ImageColor
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
 :mod:`ImageDraw` Module
 -----------------------
 

docs/reference/ImageColor.rst

@@ -0,0 +1,41 @@
+.. py:module:: PIL.ImageColor
+.. py:currentmodule:: PIL.ImageColor
+
+:mod:`ImageColor` Module
+========================
+
+The :py:mod:`ImageColor` module contains color tables and converters from
+CSS3-style color specifiers to RGB tuples. This module is used by
+:py:meth:`PIL.Image.Image.new` and the :py:mod:`~PIL.ImageDraw` module, among
+others.
+
+Color Names
+-----------
+
+The ImageColor module supports the following string formats:
+
+* Hexadecimal color specifiers, given as ``#rgb`` or ``#rrggbb``. For example,
+  ``#ff0000`` specifies pure red.
+
+* RGB functions, given as ``rgb(red, green, blue)`` where the color values are
+  integers in the range 0 to 255. Alternatively, the color values can be given
+  as three percentages (0% to 100%). For example, ``rgb(255,0,0)`` and
+  ``rgb(100%,0%,0%)`` both specify pure red.
+
+* Hue-Saturation-Lightness (HSL) functions, given as ``hsl(hue, saturation%,
+  lightness%)`` where hue is the color given as an angle between 0 and 360
+  (red=0, green=120, blue=240), saturation is a value between 0% and 100%
+  (gray=0%, full color=100%), and lightness is a value between 0% and 100%
+  (black=0%, normal=50%, white=100%). For example, ``hsl(0,100%,50%)`` is pure
+  red.
+
+* Common HTML color names. The :py:mod:`~PIL.ImageColor` module provides some
+  140 standard color names, based on the colors supported by the X Window
+  system and most web browsers. color names are case insensitive. For example,
+  ``red`` and ``Red`` both specify pure red.
+
+Functions
+---------
+
+.. autofunction:: getrgb
+.. autofunction:: getcolor

docs/reference/index.rst

@@ -6,4 +6,5 @@ Reference
 
    Image
    ImageChops
+   ImageColor
    ../PIL