Add documentation for CompiledPath

docs/source/index.rst

@@ -16,6 +16,7 @@ Enable Documentation
   kiva/backends.rst
   kiva/quickref.rst
   kiva/fonts.rst
+  kiva/compiled_path.rst
 
   credits.rst
 

docs/source/kiva/compiled_path.rst

@@ -0,0 +1,35 @@
+CompiledPath
+============
+
+A path is a collection of geometric objects that can be drawn in a graphics
+context with coloring and an affine transformation applied to it. It is the
+basic unit of drawing in a graphics context.
+
+Every graphics context instance has a current path which can be manipulated by
+the :ref:`kiva_path_functions`. However, some drawing operations are easier to
+implement with an independent path instance
+(specifically :py:meth:`draw_path_at_points`).
+
+An independent path instance can be created in two ways. The first is via the
+:py:meth:`GraphicsContext.get_empty_path` method. The second method is to use
+the :class:`CompiledPath` class imported from the backend being used. The
+interface of a :class:`CompiledPath` instance is the same as the
+:ref:`kiva_path_functions` (modulo :py:meth:`get_empty_path`).
+
+Once you have a path object, it can be drawn by adding it to the graphics
+context with the :py:meth:`GraphicsContext.add_path` method (which adds the path
+to the current path) and then calling any of the :ref:`kiva_drawing_functions`
+which operate on the current path.
+
+For certain backends which support it, the
+:py:meth:`GraphicsContext.draw_path_at_points` method can be used to draw a
+path object at many different positions with a single function call.
+
+Example
+-------
+.. image:: images/compiled_path_ex.png
+  :width: 300
+  :height: 300
+
+.. literalinclude:: compiled_path_ex.py
+  :linenos:

docs/source/kiva/compiled_path_ex.py

@@ -0,0 +1,20 @@
+from math import pi
+from kiva.agg import GraphicsContextArray as GraphicsContext
+
+gc = GraphicsContext((600, 600))
+
+path = gc.get_empty_path()
+path.move_to(10, 40)
+path.line_to(60, 40)
+path.line_to(60, 90)
+path.close_path()
+
+gc.scale_ctm(2, 2)
+gc.translate_ctm(150, 150)
+for i in range(0, 12):
+    gc.rotate_ctm(2*pi / 12.0)
+    gc.set_fill_color((i / 12.0, 0.0, 1.0 - (i / 12.0)))
+    gc.add_path(path)
+    gc.fill_path()
+
+gc.save("example.png")

docs/source/kiva/quickref.rst

@@ -83,6 +83,8 @@ Clipping functions
 .. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.even_odd_clip
 
 
+.. _kiva_path_functions:
+
 Path functions
 ~~~~~~~~~~~~~~
 The path has the concept of a "current point", which can be though of as the
@@ -104,6 +106,7 @@ position for the geometry which is added to the path.
 .. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.arc
 .. automethod:: kiva.abstract_graphics_context.AbstractGraphicsContext.arc_to
 
+.. _kiva_drawing_functions:
 
 Drawing functions
 ~~~~~~~~~~~~~~~~~
@@ -215,15 +218,6 @@ to create specific kinds of :class:`AffineMatrix` instances:
 * ``scaling_matrix(float x_scale, float y_scale)``
 * ``skewing_matrix(float x_shear, float y_shear)``
 
-
-CompiledPath
-~~~~~~~~~~~~
-A path is a collection of geometry that can be drawn in a graphics context with
-coloring and an affine transformation applied to it. It is the basic unit of
-drawing in a graphics context.
-
-Interface is the same as the `Path functions`_ .
-
 Enumerations
 ~~~~~~~~~~~~
 The following enumerations are represented by top-level constants in the "agg"