Doc update

README.md

@@ -20,3 +20,8 @@ Example:
     # Create SVG image
     top_copper.render(ctx)
     nc_drill.render(ctx, 'composite.svg')
+
+
+Rendering:
+![Composite Top Image](examples/composite_top.png)
+![Composite Bottom Image](examples/composite_bottom.png)

doc/source/conf.py

@@ -30,6 +30,7 @@ sys.path.insert(0, os.path.abspath('../../'))
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
     'numpydoc',
 ]
 

doc/source/documentation/excellon.rst

@@ -0,0 +1,42 @@
+:mod:`excellon` --- Excellon file handling
+==============================================
+
+.. module:: excellon
+   :synopsis: Functions and classes for handling Excellon files
+.. sectionauthor:: Hamilton Kibbe <ham@hamiltonkib.be>
+
+
+The Excellon format is the most common format for exporting PCB drill
+information. The Excellon format is used to program CNC drilling macines for
+drilling holes in PCBs. As such, excellon files are sometimes refererred to as
+NC-drill files.  The Excellon format reference is available 
+`here <http://www.excellon.com/manuals/program.htm>`_. The :mod:`excellon`
+submodule implements calsses to read and write excellon files without having
+to know the precise details of the format.
+
+The :mod:`excellon` submodule's :func:`read` function serves as a
+simple interface for parsing excellon files.  The :class:`ExcellonFile` class
+stores all the information contained in an Excellon file allowing the file to
+be analyzed, modified, and updated. The :class:`ExcellonParser` class is used
+in the background for parsing RS-274X files.
+
+.. _excellon-contents:
+
+Functions
+---------
+The :mod:`excellon` module defines the following functions:
+
+.. autofunction:: gerber.excellon.read
+    
+
+Classes
+-------
+The :mod:`excellon` module defines the following classes:
+
+.. autoclass:: gerber.excellon.ExcellonFile
+    :members:
+    
+
+.. autoclass:: gerber.excellon.ExcellonParser
+    :members:
+    

doc/source/documentation/gerber.rst

@@ -0,0 +1,36 @@
+:mod:`gerber` --- RS-274X file handling
+==============================================
+
+.. module:: gerber
+   :synopsis: Functions and classes for handling RS-274X  files
+.. sectionauthor:: Hamilton Kibbe <ham@hamiltonkib.be>
+
+
+The RS-274X (Gerber) format is the most common format for exporting PCB
+artwork.  The Specification is published by Ucamco and is available
+`here <http://www.ucamco.com/files/downloads/file/81/the_gerber_file_format_specification.pdf>`_.
+The :mod:`gerber` submodule implements calsses to read and write
+RS-274X files without having to know the precise details of the format.
+
+The :mod:`gerber` submodule's :func:`read` function serves as a
+simple interface for parsing gerber files.  The :class:`GerberFile` class
+stores all the information contained in a gerber file allowing the file to be
+analyzed, modified, and updated. The :class:`GerberParser` class is used in
+the background for parsing RS-274X files.
+
+.. _gerber-contents:
+Functions
+---------
+The :mod:`gerber` module defines the following functions:
+
+.. autofunction:: gerber.gerber.read
+
+Classes
+-------
+The :mod:`gerber` module defines the following classes:
+
+.. autoclass:: gerber.gerber.GerberFile
+    :members:
+
+.. autoclass:: gerber.gerber.GerberParser                                 
+    :members:

doc/source/documentation/index.rst

@@ -0,0 +1,11 @@
+Gerber Tools Reference
+======================
+
+.. toctree::
+    :maxdepth: 2
+
+    Gerber (RS-274X) Files <gerber>
+    Excellon Files <excellon>
+    Rendering <render>
+    
+

doc/source/documentation/render.rst

@@ -0,0 +1,11 @@
+:mod:`render` --- Gerber file Rendering
+==============================================
+
+.. module:: render
+   :synopsis: Functions and classes for handling Excellon files
+.. sectionauthor:: Hamilton Kibbe <ham@hamiltonkib.be>
+
+Render Module
+-------------
+.. automodule:: gerber.render.render
+    :members:

doc/source/index.rst

@@ -3,37 +3,16 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to Gerber Tools's documentation!
+Gerber-Tools!
 ========================================
 
 Contents:
 
 .. toctree::
-   :maxdepth: 2
-
-.. automodule:: gerber
-    :members:
-   
-.. automodule:: gerber.gerber
-    :members:
-
-.. automodule:: gerber.excellon
-    :members:
-
-.. automodule:: gerber.render.render
-    :members:
-
-.. automodule:: gerber.gerber_statements
-    :members:
+    :maxdepth: 1
     
-.. automodule:: gerber.excellon_statements
-    :members:
-    
-.. automodule:: gerber.cnc
-    :members:
-    
-.. automodule:: gerber.utils
-    :members:
+    intro
+    documentation/index
 
 Indices and tables
 ==================

doc/source/intro.rst

@@ -0,0 +1,19 @@
+Gerber Tools Intro
+==================
+    
+PCB CAM (Gerber) Files
+------------
+
+PCB design files (artwork) are most often stored in `Gerber` files. This is
+a generic term that may refer to `RS-274X (Gerber) <http://en.wikipedia.org/wiki/Gerber_format>`_,
+`ODB++ <http://en.wikipedia.org/wiki/ODB%2B%2B>`_, or `Excellon <http://en.wikipedia.org/wiki/Excellon_format>`_
+files.
+
+
+Gerber-Tools
+------------
+
+The gerber-tools module provides tools for working with and rendering Gerber
+and Excellon files. 
+
+

gerber/__main__.py

@@ -30,6 +30,7 @@ if __name__ == '__main__':
         print "parsing %s" % filename
         gerberfile = read(filename)
         gerberfile.render(ctx)
+        ctx.set_color(tuple([color * 0.4 for color in ctx.color]))
     print('Saving image to test.svg')
     ctx.dump('test.svg')
 

gerber/excellon.py

@@ -30,6 +30,15 @@ import math
 
 def read(filename):
     """ Read data from filename and return an ExcellonFile
+    Parameters
+        ----------
+    filename : string
+        Filename of file to parse
+
+    Returns
+    -------
+    file : :class:`gerber.excellon.ExcellonFile`
+        An ExcellonFile created from the specified file.
     """
     detected_settings = detect_excellon_format(filename)
     settings = FileSettings(**detected_settings)
@@ -75,6 +84,14 @@ class ExcellonFile(CamFile):
 
     def render(self, ctx, filename=None):
         """ Generate image of file
+
+        Parameters
+        ----------
+        ctx : :class:`gerber.render.GerberContext`
+            GerberContext subclass used for rendering the image
+
+        filename : string <optional>
+            If provided, the rendered image will be saved to `filename`
         """
         for tool, pos in self.hits:
             ctx.drill(pos[0], pos[1], tool.diameter)
@@ -89,7 +106,7 @@ class ExcellonFile(CamFile):
 
 class ExcellonParser(object):
     """ Excellon File Parser
-    
+
     Parameters
     ----------
     settings : FileSettings or dict-like
@@ -129,15 +146,15 @@ class ExcellonParser(object):
                 ymin = y if y < ymin else ymin
                 ymax = y if y > ymax else ymax
         return ((xmin, xmax), (ymin, ymax))
-    
+
     @property
     def hole_sizes(self):
         return [stmt.diameter for stmt in self.statements if isinstance(stmt, ExcellonTool)]
-    
+
     @property
     def hole_count(self):
         return len(self.hits)
-    
+
     def parse(self, filename):
         with open(filename, 'r') as f:
             for line in f:
@@ -316,7 +333,7 @@ def detect_excellon_format(filename):
     # Bail out here if we got everything....
     if detected_format is not None and detected_zeros is not None:
         return {'format': detected_format, 'zero_suppression': detected_zeros}
-    
+
     # Otherwise score each option and pick the best candidate
     else:
         scores = {}
@@ -338,4 +355,3 @@ def _layer_size_score(size, hole_count, hole_area):
     hole_score = (hole_percentage - 0.25) ** 2
     size_score = (board_area - 8) **2
     return hole_score * size_score
-    

gerber/gerber.py

@@ -15,12 +15,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-"""
-Gerber File module
-==================
-**Gerber File module**
-
-This module provides an RS-274-X class and parser
+""" This module provides an RS-274-X class and parser.
 """
 
 
@@ -34,6 +29,16 @@ from .cam import CamFile, FileSettings
 
 def read(filename):
     """ Read data from filename and return a GerberFile
+
+    Parameters
+    ----------
+    filename : string
+        Filename of file to parse
+
+    Returns
+    -------
+    file : :class:`gerber.gerber.GerberFile`
+        A GerberFile created from the specified file.
     """
     return GerberParser().parse(filename)
 
@@ -113,6 +118,14 @@ class GerberFile(CamFile):
 
     def render(self, ctx, filename=None):
         """ Generate image of layer.
+
+        Parameters
+        ----------
+        ctx : :class:`GerberContext`
+            GerberContext subclass used for rendering the image
+
+        filename : string <optional>
+            If provided, the rendered image will be saved to `filename`
         """
         ctx.set_bounds(self.bounds)
         for statement in self.statements: