Add API docs. Closes #41.

docs/api.rst

@@ -0,0 +1,15 @@
+===
+API
+===
+
+.. toctree::
+    :maxdepth: 1
+
+    api/chart
+    api/grid
+    api/lattice
+    api/scales
+    api/axis
+    api/series
+    api/shapes
+    api/theme

docs/api/axis.rst

@@ -0,0 +1,8 @@
+====
+Axis
+====
+
+.. automodule:: leather.axis
+    :no-members:
+
+.. autoclass:: leather.Axis

docs/api/chart.rst

@@ -0,0 +1,50 @@
+=====
+Chart
+=====
+
+.. automodule:: leather.chart
+    :no-members:
+
+.. autosummary::
+    :nosignatures:
+
+    leather.Chart
+
+Adding data
+-----------
+
+.. autosummary::
+    :nosignatures:
+
+    leather.Chart.add_series
+    leather.Chart.add_bars
+    leather.Chart.add_columns
+    leather.Chart.add_dots
+    leather.Chart.add_lines
+
+Customizing
+-----------
+
+.. autosummary::
+    :nosignatures:
+
+    leather.Chart.set_x_scale
+    leather.Chart.set_y_scale
+    leather.Chart.set_x_axis
+    leather.Chart.set_y_axis
+
+Rendering
+---------
+
+.. autosummary::
+    :nosignatures:
+
+    leather.Chart.to_svg
+    leather.Chart.to_svg_group
+
+Detailed list
+-------------
+
+.. autoclass:: leather.Chart
+    :members:
+    :inherited-members:

docs/api/grid.rst

@@ -0,0 +1,8 @@
+====
+Grid
+====
+
+.. automodule:: leather.grid
+    :no-members:
+
+.. autoclass:: leather.Grid

docs/api/lattice.rst

@@ -0,0 +1,8 @@
+=======
+Lattice
+=======
+
+.. automodule:: leather.lattice
+    :no-members:
+
+.. autoclass:: leather.Lattice

docs/api/scales.rst

@@ -0,0 +1,12 @@
+======
+Scales
+======
+
+.. automodule:: leather.scales
+    :no-members:
+
+.. autoclass:: leather.Scale
+
+.. autoclass:: leather.Linear
+
+.. autoclass:: leather.Ordinal

docs/api/series.rst

@@ -0,0 +1,8 @@
+======
+Series
+======
+
+.. automodule:: leather.series
+    :no-members:
+
+.. autoclass:: leather.Series

docs/api/shapes.rst

@@ -0,0 +1,16 @@
+======
+Shapes
+======
+
+.. automodule:: leather.shapes
+    :no-members:
+
+.. autoclass:: leather.Shape
+
+.. autoclass:: leather.Bars
+
+.. autoclass:: leather.Columns
+
+.. autoclass:: leather.Dots
+
+.. autoclass:: leather.Lines

docs/api/theme.rst

@@ -0,0 +1,7 @@
+=====
+Theme
+=====
+
+.. automodule:: leather.theme
+    :members:
+    :undoc-members:

docs/index.rst

@@ -10,6 +10,7 @@ leather |release|
 
     about
     install
+    api
     release_process
     license
 
@@ -18,6 +19,7 @@ Show me docs
 
 * `About <about.html>`_ - why you should use leather and the principles that guide its development
 * `Install <install.html>`_ - how to install for users and developers
+* `API <api.html>`_ - technical documentation for every agate feature
 
 Show me code
 ============

leather/__init__.py

@@ -6,7 +6,7 @@
 from leather.grid import Grid
 from leather.lattice import Lattice
 from leather.legend import Legend
-from leather.scales import Linear, Ordinal
+from leather.scales import Scale, Linear, Ordinal
 from leather.series import Series
-from leather.shapes import Bars, Columns, Dots, Lines
+from leather.shapes import Shape, Bars, Columns, Dots, Lines
 from leather import theme

leather/axis.py

@@ -4,25 +4,25 @@
 
 import six
 
-from leather.renderable import Renderable
 from leather import theme
 
 
-class Axis(Renderable):
+class Axis(object):
     """
     A horizontal or vertical chart axis.
 
     :param ticks:
-        The number of ticks to display for this axis.
+        The number of ticks to display for this axis. Defaults to
+        :data:`.theme.default_ticks`
     :param tick_formatter:
         An optional function to call on every tick. The function must take
         three arguments: :code:`(value, index, count)` where :code:`value` is
         the tick, :code:`index` is the index of the tick, and :code:`count`
         is the total number of ticks. The return value of the function will
         be used for display instead of the original tick value.
     """
-    def __init__(self, ticks=5, tick_formatter=None):
-        self._ticks = ticks
+    def __init__(self, ticks=None, tick_formatter=None):
+        self._ticks = ticks or theme.default_ticks
         self._tick_formatter = tick_formatter
 
     def estimate_label_margin(self, scale, orient):

leather/chart.py

@@ -18,10 +18,13 @@
 class Chart(object):
     """
     Container for all chart types.
+
+    :param title:
+        An optional title that will be rendered at the top of the chart.
     """
     def __init__(self, title=None):
         self._title = title
-        self._series_colors = copy(theme.series_colors)
+        self._series_colors = copy(theme.default_series_colors)
 
         self._layers = []
         self._types = [None, None]
@@ -30,43 +33,44 @@ def __init__(self, title=None):
 
     def _set_scale(self, dimension, scale):
         """
-        Set a new scale for this chart.
+        Set a new :class:`.Scale` for this chart.
         """
         self._scales[dimension] = scale
 
     def set_x_scale(self, scale):
         """
-        Set the X scale for this chart.
+        Set the X :class:`.Scale` for this chart.
         """
         self._set_scale(X, scale)
 
     def set_y_scale(self, scale):
         """
-        Set the Y scale for this chart.
+        Set the Y :class:`.Scale` for this chart.
         """
         self._set_scale(Y, scale)
 
     def _set_axis(self, dimension, axis):
         """
-        Set a new axis for this chart.
+        Set a new :class:`.Axis` for this chart.
         """
         self._axes[dimension] = axis
 
     def set_x_axis(self, axis):
         """
-        Set the X axis for this chart.
+        Set the X :class:`.Axis` for this chart.
         """
         self._set_axis(X, axis)
 
     def set_y_axis(self, axis):
         """
-        Set the Y axis for this chart.
+        Set the Y :class:`.Axis` for this chart.
         """
         self._set_axis(Y, axis)
 
     def add_series(self, series):
         """
-        Add a data :class:`.Series` to the chart.
+        Add a data :class:`.Series` to the chart. The data types of the new
+        series must be consistent with any series that have already been added.
         """
         for dim in DIMENSIONS:
             if not self._types[dim]:
@@ -78,7 +82,7 @@ def add_series(self, series):
 
     def add_bars(self, data, name=None, color=None):
         """
-        Shortcut method for adding a bar series to the chart.
+        Create and add a :class:`.Series` rendered with :class:`.Bars`.
         """
         if not color:
             color = self._series_colors.pop(0)
@@ -87,7 +91,7 @@ def add_bars(self, data, name=None, color=None):
 
     def add_columns(self, data, name=None, color=None):
         """
-        Shortcut method for adding a column series to the chart.
+        Create and add a :class:`.Series` rendered with :class:`.Columns`.
         """
         if not color:
             color = self._series_colors.pop(0)
@@ -96,7 +100,7 @@ def add_columns(self, data, name=None, color=None):
 
     def add_dots(self, data, name=None, color=None):
         """
-        Shortcut method for adding a dotted series to the chart.
+        Create and add a :class:`.Series` rendered with :class:`.Dots`.
         """
         if not color:
             color = self._series_colors.pop(0)
@@ -105,7 +109,7 @@ def add_dots(self, data, name=None, color=None):
 
     def add_lines(self, data, name=None, color=None):
         """
-        Shortcut method for adding a line series to the chart.
+        Create and add a :class:`.Series` rendered with :class:`.Lines`.
         """
         if not color:
             color = self._series_colors.pop(0)
@@ -131,13 +135,18 @@ def _validate_dimension(self, dimension):
 
         return (scale, axis)
 
-    def to_svg_group(self, width, height):
+    def to_svg_group(self, width=None, height=None):
         """
-        Render the completechart to an SVG group element that can be placed
-        inside an :code:`<svg>` tag.
+        Render this chart to an SVG group element.
+
+        This can then be placed inside an :code:`<svg>` tag to make a complete
+        SVG graphic.
 
-        See :meth:`to_svg` for argument descriptions.
+        See :meth:`.Chart.to_svg` for arguments.
         """
+        width = width or theme.default_width
+        height = height or theme.default_height
+
         if not self._layers:
             raise ValueError('You must add at least one series to the chart before rendering.')
 
@@ -238,7 +247,7 @@ def to_svg(self, path=None, width=None, height=None):
         """
         Render this chart to an SVG document.
 
-        Note: :code:`width` and :code:`height` are specified in SVG's
+        The :code:`width` and :code:`height` are specified in SVG's
         "unitless" units, however, it is usually convenient to specify them
         as though they were pixels.
 
@@ -247,12 +256,14 @@ def to_svg(self, path=None, width=None, height=None):
             will be returned as a string. If running within IPython, then this
             will return a SVG object to be displayed.
         :param width:
-            The output width, in SVG user units.
+            The output width, in SVG user units. Defaults to
+            :data:`.theme.default_chart_width`.
         :param height:
-            The output height, in SVG user units.
+            The output height, in SVG user units. Defaults to
+            :data:`.theme.default_chart_height`.
         """
-        width = width or theme.default_width
-        height = height or theme.default_height
+        width = width or theme.default_chart_width
+        height = height or theme.default_chart_height
 
         root = ET.Element('svg',
             width=six.text_type(width),

leather/data_types.py

@@ -7,7 +7,7 @@
 
 class DataType(object):
     """
-    Base class for series data types.
+    Base class for :class:`.Series` data types.
     """
     @classmethod
     def infer(cls, v):

leather/grid.py

@@ -13,20 +13,27 @@
 
 class Grid(object):
     """
-    A grid of charts rendered together.
+    A container for a set of :class:`.Chart` instances that are rendered in a
+    grid layout.
     """
     def __init__(self):
         self._charts = []
 
     def add_chart(self, chart):
         """
-        Add a chart to the grid.
+        Add a :class:`.Chart` to the grid.
         """
         self._charts.append(chart)
 
     def to_svg(self, path=None, width=None, height=None):
         """
         Render the grid to an SVG.
+
+        The :code:`width` and :code:`height` arguments refer to the size of the
+        entire grid. The size of individual charts will be inferred
+        automatically.
+
+        See :meth:`.Chart.to_svg` for arguments.
         """
         if not width or not height:
             count = len(self._charts)