Documentation (#13)

celiagg · Dec 7, 2016 · 1dd5696 · 1dd5696
1 parent 5b39368
commit 1dd5696
Show file tree

Hide file tree

Showing 15 changed files with 1,199 additions and 137 deletions.
diff --git a/README.rst b/README.rst
@@ -16,6 +16,8 @@ render directly into a Numpy array.
 A respectably modern compiler is required to build celiagg
 (one supporting certain C++11 features).
 
+`Documentation! <https://celiagg.github.io/celiagg/>`_
+
 Installation
 ------------
 

diff --git a/celiagg/__init__.py b/celiagg/__init__.py
@@ -35,4 +35,4 @@
     TextDrawingMode, Transform
 )
 from ._celiagg import (CanvasG8, CanvasGA16, CanvasRGB24, CanvasRGBA32,
-                     CanvasBGRA32, CanvasRGBA128)
+                       CanvasBGRA32, CanvasRGBA128)
diff --git a/celiagg/conversion.pxi b/celiagg/conversion.pxi
@@ -57,7 +57,7 @@ cdef float _get_max_value(dtype):
 
 
 cdef gray2rgb(src, dst_order, dtype=None, alpha=False):
-    """ Convert gray pixels to RGB[A].
+    """Convert gray pixels to RGB[A].
     """
     last_dim = (4,) if alpha else (3,)
     dst = numpy.empty(src.shape + last_dim, dtype=dtype)
@@ -76,7 +76,7 @@ cdef gray2rgb(src, dst_order, dtype=None, alpha=False):
 
 
 cdef rgb2rgb(src, src_order, dst_order, dtype=None, alpha=False):
-    """ Convert RGB[A] pixels to RGB[A] pixels.
+    """Convert RGB[A] pixels to RGB[A] pixels.
     """
     last_dim = (4,) if alpha else (3,)
     dst = numpy.empty(src.shape[:2] + last_dim, dtype=dtype)
@@ -98,7 +98,7 @@ cdef rgb2rgb(src, src_order, dst_order, dtype=None, alpha=False):
 
 
 cdef gray2gray(src, dtype=None):
-    """ Convert gray pixels to gray pixels.
+    """Convert gray pixels to gray pixels.
     """
     dst = numpy.empty(src.shape, dtype=dtype)
     max_from = _get_max_value(src.dtype)
@@ -108,7 +108,7 @@ cdef gray2gray(src, dtype=None):
 
 
 cdef rgb2gray(src, src_order, dtype=None):
-    """ Convert RGB[A] pixels to gray.
+    """Convert RGB[A] pixels to gray.
     """
     dst = numpy.empty(src.shape[:2], dtype=dtype)
 
@@ -123,9 +123,10 @@ cdef rgb2gray(src, src_order, dtype=None):
 def convert_image(src, to_format, bottom_up=False):
     """convert_image(src, to_format, bottom_up=False)
     Create a new image with a desired pixel format and orientation.
-    image: An Image instance
-    to_format: A PixelFormat describing the desired output format
-    bottom_up: If True, the image data is flipped in the y axis
+
+    :param image: An Image instance
+    :param to_format: A PixelFormat describing the desired output format
+    :param bottom_up: If True, the image data is flipped in the y axis
     """
     if not isinstance(src, Image):
         raise TypeError("src must an Image instance")

diff --git a/celiagg/font.pxi b/celiagg/font.pxi
@@ -30,14 +30,15 @@ cpdef enum FontCacheType:
 
 IF _ENABLE_TEXT_RENDERING:
     cdef class Font:
+        """Font(path, size, cache_type)
+
+        :param path: A Unicode string containing the path of a ``Font`` file
+        :param size: The size of the font
+        :param cache_type: A ``FontCacheType``
+        """
         cdef _font.Font* _this
 
         def __cinit__(self, fontName, double size, FontCacheType ch):
-            """Font(path, height, bold, italic, cache_type)
-            path : A unicode string containing the path of a Font file
-            height : The size of the font
-            cache_type : A FontCacheType
-            """
             fontName = _get_utf8_text(fontName,
                                     "Font path must be a unicode string")
             self._this = new _font.Font(fontName, size, ch)
@@ -68,13 +69,18 @@ IF _ENABLE_TEXT_RENDERING:
                 self._this.hinting(value)
 
         def width(self, text):
-            """width(self, text):
-            text : a unicode string
+            """width(text)
+            Measures the width of a string rendered with the font.
+
+            :param text: a unicode string
             """
             text = _get_utf8_text(text, "Argument must be a unicode string")
             return self._this.string_width(text)
 ELSE:
     cdef class Font:
+        """Font()
+        NOTE: celiagg was compiled without text rendering support!
+        """
         def __init__(self, *args):
             msg = ("The celiagg library was compiled without font support!  "
                    "If you would like to render text, you will need to "

diff --git a/celiagg/graphics_state.pxi b/celiagg/graphics_state.pxi
@@ -27,6 +27,14 @@ from libcpp.vector cimport vector
 
 
 cdef class Rect:
+    """Rect(x, y, w, h)
+    A rectangle.
+
+    :param x: The X coordinate of the top left corner
+    :param y: The Y coordinate of the top left corner
+    :param w: The width of the rectangle in pixels
+    :param h: The height of the rectangle in pixels
+    """
     cdef _graphics_state.Rect* _this
 
     def __cinit__(self, double x=0., double y=0., double w=0., double h=0.):
@@ -82,6 +90,30 @@ cdef class Rect:
 
 
 cdef class GraphicsState:
+    """GraphicsState(**properties)
+    A container for drawing state. Can be initialized using keyword
+    arguments and works as a namespace for the following properties:
+
+    * anti_aliased: A boolean denoting whether drawing is anti-aliased or not.
+    * drawing_mode: A ``DrawingMode`` value denoting the drawing mode.
+    * text_drawing_mode: A ``TextDrawingMode`` value denoting the text drawing
+                         mode.
+    * blend_mode: A ``BlendMode`` for non-image drawing. (ignored)
+    * image_blend_mode: A ``BlendMode`` for image drawing. (ignored)
+    * line_cap: A ``LineCap`` value denoting the style of line ends.
+    * line_join: A ``LineJoin`` value denoting the style of joins.
+    * inner_join: An ``InnerJoin`` value denoting the style of inner joins.
+    * miter_limit: The miter limit
+    * inner_miter_limit: The miter limit for inner joins
+    * master_alpha: A master opacity value.
+    * line_width: The width when stroking lines.
+    * clip_box: A ``Rect`` which defines a simple clipping area.
+    * line_dash_pattern: A sequence of (dash length, gap length) pairs.
+    * line_dash_phase: Where in ``line_dash_pattern`` to start, when drawing.
+    * stencil: An ``Image`` with format ``Gray8`` which will mask any drawing.
+               The dimensions must match the size of the canvas that is being
+               drawn to.
+    """
     cdef _graphics_state.GraphicsState* _this
     cdef Image _stencil_img
 
@@ -104,7 +136,7 @@ cdef class GraphicsState:
                               GetSetDescriptorType)]
 
     def copy(self):
-        """ Return a deep copy of the object
+        """Return a deep copy of the object
         """
         cpy = GraphicsState()
         properties = self._propnames()

diff --git a/celiagg/image.pxi b/celiagg/image.pxi
@@ -109,9 +109,10 @@ cdef img_ptr_t _get_image(array, pixel_format, bottom_up):
 
 cdef class Image:
     """Image(array, pixel_format, bottom_up=False)
-        image: A 2D or 3D numpy array containing image data
-        pixel_format: A PixelFormat describing the image's pixel format
-        bottom_up: If True, the image data starts at the bottom of the image
+
+    :param image: A 2D or 3D numpy array containing image data
+    :param pixel_format: A PixelFormat describing the image's pixel format
+    :param bottom_up: If True, the image data starts at the bottom of the image
     """
     cdef img_ptr_t _this
     cdef PixelFormat pixel_format
@@ -151,7 +152,7 @@ cdef class Image:
         del self._this
 
     def copy(self):
-        """ Returns a deep copy of the image.
+        """Returns a deep copy of the image.
         """
         array = self.pixel_array.copy()
         return Image(array, self.pixel_format, bottom_up=self.bottom_up)