Add to the documentation

Move content of API.txt into the docs
Rename TODO.txt and add it to the docs

boxes/edges.py

@@ -19,6 +19,7 @@ import math
 
 class BoltPolicy:
     """Abstract class
+
     Distributes (bed) bolts on a number of segments
     (fingers of a finger joint)
 
@@ -97,8 +98,12 @@ class Settings:
     """Generic Settings class
 
     Used by different other classes to store messurements and details.
-    Supports absolutevalues and settings that grow with the thinckness
+    Supports absolute values and settings that grow with the thickness
     of the material used.
+
+    Overload the absolute_params and relative_params class attributes with
+    the suported keys and default values. The values are available via
+    attribute access.
     """
     absolute_params = { }
     relative_params = { }
@@ -118,8 +123,8 @@ class Settings:
         Set values
 
         :param thickness: thickness of the material used
-        :param relative:  (Default value = True) Do scale by thinckness
+        :param relative:  (Default value = True) Do scale by thickness
-        :param **kw: parameters to set
+        :param \*\*kw: parameters to set
 
         """
         factor = 1.0
@@ -156,6 +161,7 @@ class Edge:
         return getattr(self.boxes, name)
 
     def __call__(self, length, **kw):
+        """Draw edge of length mm"""
         self.ctx.move_to(0,0)
         self.ctx.line_to(length, 0)
         self.ctx.translate(*self.ctx.get_current_point())
@@ -252,9 +258,23 @@ class SlottedEdge(Edge):
         self.edge(self.sections[-1])
 
 class FingerJointSettings(Settings):
-    """Setting for all different finger joint components
+    """Settings for finger joints
 
-    Both sides should use the same instance to ensure they match"""
+Values:
+
+* absolute
+
+  * surroundingspaces : 2 : maximum space at the start and end in multiple
+    of normal spaces
+
+* relative (in multiples of thickness)
+
+  * space : 1.0 : space between fingers
+  * finger : 1.0 : width of the fingers
+  * height : 1.0 : length of the fingers
+  * width : 1.0 : width of finger holes
+
+"""
 
     absolute_params = {
         "surroundingspaces" : 2,
@@ -350,7 +370,7 @@ class FingerHoleEdge(Edge):
         return (self.fingerHoleEdgeWidth+1) * self.thickness
 
 class FingerHoles:
-    """Hole mathcing a finger joint edge"""
+    """Hole matching a finger joint edge"""
     def __init__(self, boxes, settings):
         self.boxes = boxes
         self.ctx = boxes.ctx
@@ -392,7 +412,19 @@ class CrossingFingerHoleEdge(Edge):
 class DoveTailSettings(Settings):
     """Settings used for dove tail joints
 
-    Both sides should use the same instance to ensure they match"""
+Values:
+
+* absolute
+
+  * angle : 50 : how much should fingers widen (-80 to 80)
+
+* relative (in multiples of thickness)
+
+  * size : 3 : from one middle of a dove tail to another
+  * depth : 1.5 : how far the dove tails stick out of/into the edge
+  * radius : 0.2 : radius used on all four corners
+
+"""
     absolute_params = {
         "angle" : 50,
         }
@@ -454,7 +486,21 @@ class DoveTailJointCounterPart(DoveTailJoint):
         return self.boxes.spacing
 
 class FlexSettings(Settings):
-    """Settings for one directional flex cuts"""
+    """Settings for one directional flex cuts
+
+Values:
+
+* absolute
+
+ * stretch : 1.05 : Hint of how much the flex part should be shortend
+
+* relative (in multiples of thickness)
+
+ * distance : 0.5 : width of the pattern perpendicular to the cuts
+ * connection : 1.0 : width of the gaps in the cuts
+ * width" : 5.0 : width of the pattern in direction of the cuts
+
+"""
     relative_params = {
         "distance" : 0.5,
         "connection" : 1.0,

documentation/API.txt

@@ -1,91 +0,0 @@
-Basic Concepts
-==============
-
-There is basically only one class that takes care of everything. You
-are supposed to sub class it and implement the render() method
-(actually just any method that does anything). This Boxes class keeps
-a cairo canvas object (self.ctx) that all drawing is made on. In
-addition it keeps a couple of global settings used for various drawing
-operations. See the __init__ method for the details.
-
-Building blocks and coordinates
--------------------------------
-
-To avoid too much coordinate calculations the coordinate system is
-continuously moved to the current point. The most basic functions just
-do drawings relative to the current coordinate system - without
-changing the coordinate system. Those are found in the Builing Blocks section.
-
-Turtle graphics commands
-------------------------
-
-These start at the current positions and move the coordinate system to
-their end. It is assumed that you are (roughly) drawing into the
-direction of the x axis, with the inside of the part being above the
-line. You need to turn counter clockwise (mathematically positive) to
-get a closed shape. These commands typically produce some sort of edges.
-
-Finger joints
-.............
-
-Finger joints are a simple way of joining two sheets of plywood. They
-work best at an 90° angle. There are two different sides matching each
-other. As a third alternative there are holes that the fingers of one
-sheet can plug into. This allows stable T connections especially
-useful for inner walls.
-
-Dovetail joints
-...............
-
-Dovetails joints can only be used to join two pieces flatly. This
-limits their use to closing some round form created with flex areas or
-for joining several parts to a bigger one. For this use case they are
-much stronger than simple finger joints and can also bare pulling forces.
-
-
-Whole parts
-===========
-
-A couple of command can create whole parts like walls. Typically the
-sizes given are the inner dimmensions not including additional space
-needed for burn compensation or joints.
-
-Currently there are only three such parts:
-
-Boxes.rectangularWall() for generic walls and
-Boxes.roundedPlate() and Boxes.surroundingWall() for a wall with
-rounded corners and fitting wall with flex for the rounded edges and
-dove tail joints for closing the loop.
-
-Callback parameter
-..................
-
-The callback parameter can take on of the following forms:
-
- * A function (or bound method) that expects one parameter: the number
-   of the side the callback is currently called for. 
- * A dict with some of the numbers of the sides as keys and functions
-   without parameters as values.
- * A list of functions without parameters. The list may contain None
-   as place holder and be shorter than the number of sides. 
-
-The callback functions are called with the side of the part at the
-positive x and y axis. If the edge uses up space this space is below
-the x axis. You do not have to restore the coordinate settings in the
-callback.
-
-Instead of functions it can be handy to use a lambda expression
-calling the one building block funtion you need (e.g. fingerHolesAt).
-
-Edge description
-................
-
-Some part building functions take a edges param or have other params
-describing some edges. These descriptions are one or several character
-strings. With the following meanings: 
-
- e : straight edge
- E : as above but extended outside by one thickness
- f, F : finger joints
- h : edge with holes for finger joints
- d, D : dove tail joints

documentation/Boxes.rst

@@ -1,6 +1,4 @@
 
-		 
-
 ==========================
 The boxes.Boxes main class
 ==========================
@@ -8,8 +6,17 @@ The boxes.Boxes main class
 .. toctree::
       :maxdepth: 2
 		 
+There is basically one class that takes care of everything. You are
+supposed to sub class it and implement the ``.__init__()`` and
+``.render()`` method. This Boxes class keeps a cairo canvas object
+(self.ctx) that all drawing is made on. In addition it keeps a couple
+of global settings used for various drawing operations. See the
+``.__init__()`` method for the details.
+
 .. autoclass:: boxes.Boxes
 
+And easier way to get started is using the
+``boxes/generators/_template.py`` as a basis for your own generators.
 
 Basic operation
 ---------------
@@ -38,13 +45,131 @@ Currently there are only three such parts:
 The callback parameter
 ......................
 
+The callback parameter can take on of the following forms:
+
+* A function (or bound method) that expects one parameter: the number of the side the callback is currently called for.
+* A dict with some of the numbers of the sides as keys and functions without parameters as values.
+* A list of functions without parameters. The list may contain None as place holder and be shorter than the number of sides. 
+
+The callback functions are called with the side of the part at the
+positive x and y axis. If the edge uses up space this space is below
+the x axis. You do not have to restore the coordinate settings in the
+callback.
+
+Instead of functions it can be handy to use a lambda expression
+calling the one building block funtion you need (e.g. fingerHolesAt).
+
+For your own parts you can use this helper function:
+
 .. automethod:: boxes.Boxes.cc
+
+For finding the right piece to the *callback* parameter this function is used:
+
 .. automethod:: boxes.Boxes.getEntry
 
+		
 The move parameter
 ..................
 
+For placing the parts the ``move`` parameter can be used. It is string
+with space separated words - at most one of each of those options: 
+
+* left / right
+* up / down
+* only
+
+If "only" is given the part is not drawn but only the move is
+done. This can be useful to go in one direction after having placed
+multiple parts in the other and have returned with ``.ctx.restore()``.
+
+For implementing parts the following helper function can be used to
+implement a ``move`` parameter:
+
 .. automethod:: boxes.Boxes.move
 
+It needs to be called before and after drawing the actual part with
+the proper ``before`` paramter set.
+		
 The edges parameter
 ...................
+
+The ``edges`` parameter needs to be an iterable of Edge instances to be
+used as edges of the part. Instead of instances it is possible to pass
+a single character that is looked up in the ``.edges`` dict. This
+allows to pass a string with the desired characters per edge. By
+default the following character are supported:
+
+* e : straight edge
+* E : as above but extended outside by one thickness
+* f, F : finger joints
+* h : edge with holes for finger joints
+* d, D : dove tail joints
+
+Generators can register their own Edges by putting them into the
+``.edges`` dictionary.
+
+Same applies to the parameters of ``.surroundingWall`` although they
+denominate single edge (types) only.
+  
+Navigation
+----------
+.. automethod:: boxes.Boxes.moveTo
+.. automethod:: boxes.Boxes.continueDirection
+
+Boxes.ctx.save()
+Boxes.ctx.restore()
+
+Turtle Graphics commands
+------------------------
+
+These commands all move the coordinate system with them.
+
+.. automethod:: boxes.Boxes.edge
+.. automethod:: boxes.Boxes.corner
+.. automethod:: boxes.Boxes.curveTo
+.. automethod:: boxes.Boxes.polyline
+
+Special Functions
+.................
+
+.. automethod:: boxes.Boxes.bedBoltHole
+
+Latch and Grip
+..............
+
+These should probably be Edge classes. But right now they are still functions.
+
+.. automethod:: boxes.Boxes.grip
+.. automethod:: boxes.Boxes.latch
+.. automethod:: boxes.Boxes.handle
+
+Draw Commands
+-------------
+
+These commands do not change the coordinate system but get the
+coordinates passed as parameters. All of them are either som sort of
+hole or text. These artefacts are placed somewhere independently of
+some continuous outline of the part their on.
+
+.. automethod:: boxes.Boxes.fingerHolesAt
+.. automethod:: boxes.Boxes.hole
+.. automethod:: boxes.Boxes.rectangularHole
+.. automethod:: boxes.Boxes.text
+.. automethod:: boxes.Boxes.NEMA
+
+Hexagonal Hole patterns
+.......................
+
+Hexagonal hole patters are one way to have some ventilation for
+housings maded with Boxes.py. Right now both ``.rectangularWall()``
+and ``.roundedPlate()`` do supports this pattern directly by passing
+the parameters to the calls. For other use cases these more low level
+methods can be used.
+
+For now this is the only supported pattern for ventilation slots. More
+may be added in the future.
+
+.. automethod:: boxes.Boxes.hexHolesRectangle
+.. automethod:: boxes.Boxes.hexHolesCircle
+.. automethod:: boxes.Boxes.hexHolesPlate
+.. automethod:: boxes.Boxes.hexHolesHex

documentation/TODO.rst

@@ -1,12 +1,18 @@
+=====
+To Do
+=====
+
 Infrastructure
 ..............
 
 * Make outer edge continuous even if other parts are drawn intermediately.
 * Check burn compensation for building blocks
-* Fix hexHoles* (leftoover, grow to space, ...)
+* Fix hexHoles\* (leftoover, grow to space, ...)
 * Add other ventilation patterns than hex holes
 * Make settings nicer
- * Offer a collection of different settings
+
+  * Offer a collection of different settings
+
 * Use stretch setting in flexboxes
 * Add CLI params for finger joint settings
 * Add CLI params for flex settings
@@ -15,8 +21,10 @@ Generators
 ..........
 
 * Fix traylayout
- * Inner corners of the floor
+
- * Bottom edges of walls without floor underneeth
+  * Inner corners of the floor
+  * Bottom edges of walls without floor underneeth
+
 * Finish lamp
 * Make bolts configurable (e.g. box2.py)
 * Treasure Chest with rounded lid and living hinge

documentation/edges.rst

@@ -2,22 +2,105 @@ Edges
 =====
 
 As edges started out as methods of the main Boxes class they still are
-callables and they are still available as both attributes of the Boxes
+callables. A set of instances are kept the ``.edges`` attribute of the
-instance and also via the **.edges** attribute.
+``Boxes`` class. It is a dict with strings of length one as keys:
 
-The default edges have a one character short name that can be used at
+* e : Edge
-various places to quickly decide which type of edge to use.
+* E : OutSetEdge
+* f : FingerJointEdge
+* F : FingerJointEdgeCounterPart
+* h : FingerHoleEdge
+* d : DoveTailJoint
+* D : DoveTailJointCounterPart
+
+Edges of the same type share a settings instance to make sure both
+sides match (when the same length is given).
+
+Edge base class
+---------------
+
+.. autoclass:: boxes.edges.Edge
+	       :members:
+
+.. automethod:: boxes.edges.Edge.__call__
+
+Settings Class
+--------------
+
+.. autoclass:: boxes.edges.Settings
+	       :members:
+
+
+Straight Edges
+--------------
 
 .. autoclass:: boxes.edges.Edge
 .. autoclass:: boxes.edges.OutSetEdge
+
+Finger joints
+-------------
+
+Finger joints are a simple way of joining two sheets (e.g. of plywood). They
+work best at an 90° angle. There are two different sides matching each
+other. As a third alternative there are holes that the fingers of one
+sheet can plug into. This allows stable T connections especially
+useful for inner walls.
+
 .. autoclass:: boxes.edges.FingerJointEdge
 .. autoclass:: boxes.edges.FingerJointEdgeCounterPart
 .. autoclass:: boxes.edges.FingerHoleEdge
 .. autoclass:: boxes.edges.CrossingFingerHoleEdge
+
+In addition there is
+
+.. automethod:: boxes.Boxes.fingerHolesAt
+
+which is no Edge but fits ``FingerJointEdge``.
+
+Finger Joint Settings
+.....................
+
+.. autoclass:: boxes.edges.FingerJointSettings
+	       :members:
+
+Bed Bolts
+.........
+
+.. autoclass:: boxes.edges.BoltPolicy
+
+.. autoclass:: boxes.edges.Bolts
+
+Dove Tail Joints
+----------------
+Dovetails joints can only be used to join two pieces flatly. This
+limits their use to closing some round form created with flex areas or
+for joining several parts to a bigger one. For this use case they are
+much stronger than simple finger joints and can also bare pulling forces.
+
 .. autoclass:: boxes.edges.DoveTailJoint
 .. autoclass:: boxes.edges.DoveTailJointCounterPart
+
+Dove Tail Settings
+..................
+
+.. autoclass:: boxes.edges.DoveTailSettings
+	                      :members:
+				 
+Flex
+----
 .. autoclass:: boxes.edges.FlexEdge
+
+Flex Settings
+.............
+
+.. autoclass:: boxes.edges.FlexSettings
+
+Slots
+-----
 .. autoclass:: boxes.edges.Slot
 .. autoclass:: boxes.edges.SlottedEdge
+
+CompoundEdge
+------------
 .. autoclass:: boxes.edges.CompoundEdge
 	       

documentation/index.rst

@@ -13,6 +13,7 @@ Contents:
 	      
    Boxes
    edges
+   TODO
 
 .. include:: ../README.rst