From 6566a73bcff226bdfe8dcb24c8740318fd19a770 Mon Sep 17 00:00:00 2001
From: Stephen Johnson <steve@steveasleep.com>
Date: Sun, 13 Oct 2013 21:41:21 -0700
Subject: [PATCH] Fully document PIL.ImagePath

---
 PIL/ImagePath.py             | 11 ++----
 docs/PIL.rst                 |  8 -----
 docs/reference/ImagePath.rst | 68 ++++++++++++++++++++++++++++++++++++
 docs/reference/index.rst     |  1 +
 4 files changed, 72 insertions(+), 16 deletions(-)
 create mode 100644 docs/reference/ImagePath.rst

diff --git a/PIL/ImagePath.py b/PIL/ImagePath.py
index 63e367063..656d5ce61 100644
--- a/PIL/ImagePath.py
+++ b/PIL/ImagePath.py
@@ -16,17 +16,12 @@
 
 from PIL import Image
 
-##
-# Path wrapper.
+
+# the Python class below is overridden by the C implementation.
+
 
 class Path:
 
-    ##
-    # Creates a path object.
-    #
-    # @param xy Sequence.  The sequence can contain 2-tuples [(x, y), ...]
-    #     or a flat list of numbers [x, y, ...].
-
     def __init__(self, xy):
         pass
 
diff --git a/docs/PIL.rst b/docs/PIL.rst
index 431f8f3ee..cd2252826 100644
--- a/docs/PIL.rst
+++ b/docs/PIL.rst
@@ -86,14 +86,6 @@ can be found here.
     :undoc-members:
     :show-inheritance:
 
-:mod:`ImagePath` Module
------------------------
-
-.. automodule:: PIL.ImagePath
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
 :mod:`ImageQt` Module
 ---------------------
 
diff --git a/docs/reference/ImagePath.rst b/docs/reference/ImagePath.rst
new file mode 100644
index 000000000..700464144
--- /dev/null
+++ b/docs/reference/ImagePath.rst
@@ -0,0 +1,68 @@
+.. py:module:: PIL.ImagePath
+.. py:currentmodule:: PIL.ImagePath
+
+:py:mod:`ImagePath` Module
+==========================
+
+The :py:mod:`ImagePath` module is used to store and manipulate 2-dimensional
+vector data. Path objects can be passed to the methods on the
+:py:mod:`~PIL.ImageDraw` module.
+
+.. py:class:: PIL.ImagePath.Path
+
+    A path object. The coordinate list can be any sequence object containing
+    either 2-tuples [(x, y), …] or numeric values [x, y, …].
+
+    You can also create a path object from another path object.
+
+    In 1.1.6 and later, you can also pass in any object that implements
+    Python’s buffer API. The buffer should provide read access, and contain C
+    floats in machine byte order.
+
+    The path object implements most parts of the Python sequence interface, and
+    behaves like a list of (x, y) pairs. You can use len(), item access, and
+    slicing as usual. However, the current version does not support slice
+    assignment, or item and slice deletion.
+
+    :param xy: A sequence. The sequence can contain 2-tuples [(x, y), ...]
+               or a flat list of numbers [x, y, ...].
+
+.. py:method:: PIL.ImagePath.Path.compact(distance=2)
+
+    Compacts the path, by removing points that are close to each other. This
+    method modifies the path in place, and returns the number of points left in
+    the path.
+
+    **distance** is measured as `Manhattan distance`_ and defaults to two
+    pixels.
+
+.. _Manhattan distance: http://en.wikipedia.org/wiki/Manhattan_distance
+
+.. py:method:: PIL.ImagePath.Path.getbbox()
+
+    Gets the bounding box of the path.
+
+    :return: ``(x0, y0, x1, y1)``
+
+.. py:method:: PIL.ImagePath.Path.map(function)
+
+    Maps the path through a function.
+
+.. py:method:: PIL.ImagePath.Path.tolist(flat=0)
+
+    Converts the path to a Python list [(x, y), …].
+
+    :param flat: By default, this function returns a list of 2-tuples
+                 [(x, y), ...].  If this argument is :keyword:`True`, it
+                 returns a flat list [x, y, ...] instead.
+    :return: A list of coordinates. See **flat**.
+
+.. py:method:: PIL.ImagePath.Path.transform(matrix)
+
+    Transforms the path in place, using an affine transform. The matrix is a
+    6-tuple (a, b, c, d, e, f), and each point is mapped as follows:
+
+    .. code-block:: python
+
+        xOut = xIn * a + yIn * b + c
+        yOut = xIn * d + yIn * e + f
diff --git a/docs/reference/index.rst b/docs/reference/index.rst
index 607ffe10b..8d206dbb1 100644
--- a/docs/reference/index.rst
+++ b/docs/reference/index.rst
@@ -16,4 +16,5 @@ Reference
    ImageMath
    ImageOps
    ImagePalette
+   ImagePath
    ../PIL