From 7881c86bbaf6bdaaef4caab82665fe43d3f893de Mon Sep 17 00:00:00 2001
From: Stephen Johnson <steve@steveasleep.com>
Date: Sun, 13 Oct 2013 21:22:18 -0700
Subject: [PATCH] Document PIL.ImagePalette as best I can

---
 PIL/ImagePalette.py             | 30 +++++++++++++++++++-----------
 docs/PIL.rst                    |  8 --------
 docs/reference/ImagePalette.rst | 21 +++++++++++++++++++++
 docs/reference/index.rst        |  1 +
 4 files changed, 41 insertions(+), 19 deletions(-)
 create mode 100644 docs/reference/ImagePalette.rst

diff --git a/PIL/ImagePalette.py b/PIL/ImagePalette.py
index 2fa051407..61affdb19 100644
--- a/PIL/ImagePalette.py
+++ b/PIL/ImagePalette.py
@@ -19,11 +19,9 @@
 import array
 from PIL import Image, ImageColor
 
-##
-# Colour palette wrapper for palette mapped images.
 
 class ImagePalette:
-    "Colour palette for palette mapped images"
+    "Color palette for palette mapped images"
 
     def __init__(self, mode = "RGB", palette = None):
         self.mode = mode
@@ -35,14 +33,21 @@ class ImagePalette:
             raise ValueError("wrong palette size")
 
     def getdata(self):
-        # experimental: get palette contents in format suitable
-        # for the low-level im.putpalette primitive
+        """
+        Get palette contents in format suitable # for the low-level
+        ``im.putpalette`` primitive.
+
+        .. warning:: This method is experimental.
+        """
         if self.rawmode:
             return self.rawmode, self.palette
         return self.mode + ";L", self.tobytes()
 
     def tobytes(self):
-        # experimental: convert palette to bytes
+        """Convert palette to bytes.
+
+        .. warning:: This method is experimental.
+        """
         if self.rawmode:
             raise ValueError("palette contains raw palette data")
         if isinstance(self.palette, bytes):
@@ -57,7 +62,10 @@ class ImagePalette:
     tostring = tobytes
 
     def getcolor(self, color):
-        # experimental: given an rgb tuple, allocate palette entry
+        """Given an rgb tuple, allocate palette entry.
+
+        .. warning:: This method is experimental.
+        """
         if self.rawmode:
             raise ValueError("palette contains raw palette data")
         if isinstance(color, tuple):
@@ -80,7 +88,10 @@ class ImagePalette:
             raise ValueError("unknown color specifier: %r" % color)
 
     def save(self, fp):
-        # (experimental) save palette to text file
+        """Save palette to text file.
+
+        .. warning:: This method is experimental.
+        """
         if self.rawmode:
             raise ValueError("palette contains raw palette data")
         if isinstance(fp, str):
@@ -192,6 +203,3 @@ def load(filename):
         raise IOError("cannot load palette")
 
     return lut # data, rawmode
-
-
-# add some psuedocolour palettes as well
diff --git a/docs/PIL.rst b/docs/PIL.rst
index 9b2cb37b9..431f8f3ee 100644
--- a/docs/PIL.rst
+++ b/docs/PIL.rst
@@ -86,14 +86,6 @@ can be found here.
     :undoc-members:
     :show-inheritance:
 
-:mod:`ImagePalette` Module
---------------------------
-
-.. automodule:: PIL.ImagePalette
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
 :mod:`ImagePath` Module
 -----------------------
 
diff --git a/docs/reference/ImagePalette.rst b/docs/reference/ImagePalette.rst
new file mode 100644
index 000000000..15b8aed8f
--- /dev/null
+++ b/docs/reference/ImagePalette.rst
@@ -0,0 +1,21 @@
+.. py:module:: PIL.ImagePalette
+.. py:currentmodule:: PIL.ImagePalette
+
+:py:mod:`ImagePalette` Module
+=============================
+
+The :py:mod:`ImagePalette` module contains a class of the same name to
+represent the color palette of palette mapped images.
+
+.. note::
+
+    This module was never well-documented. It hasn't changed since 2001,
+    though, so it's probably safe for you to read the source code and puzzle
+    out the internals if you need to.
+
+    The :py:class:`~PIL.ImagePalette.ImagePalette` class has several methods,
+    but they are all marked as "experimental." Read that as you will. The
+    ``[source]`` link is there for a reason.
+
+.. autoclass:: PIL.ImagePalette.ImagePalette
+    :members:
diff --git a/docs/reference/index.rst b/docs/reference/index.rst
index b996c9160..607ffe10b 100644
--- a/docs/reference/index.rst
+++ b/docs/reference/index.rst
@@ -15,4 +15,5 @@ Reference
    ImageGrab
    ImageMath
    ImageOps
+   ImagePalette
    ../PIL