Expand documentation

doc/advanced_usage.rst

@@ -25,8 +25,9 @@ For example, create a rectangular zone, and save the reference to it:
 
     .. code:: python
 
-        painter.layer("F_Cu") 
-        zone = painter.rect_zone(0,0,10,10)
+        p = CircuitPainter()
+        p.layer("F_Cu") 
+        zone = p.rect_zone(0,0,10,10)
 
 Then, modify the zone properties using the pcbnew api:
 
@@ -48,7 +49,7 @@ with some different DRC settings:
     .. code:: python
         
         import pcbnew
-        settings = painter.pcb.GetDesignSettings()
+        settings = p.pcb.GetDesignSettings()
         settings.SetCopperLayerCount(4) # Change to a 4-layer board design
         settings.m_CopperEdgeClearance = pcbnew.FromMM(0.1) # Set the copper-to-edge spacing to 0.1mm
 
@@ -68,7 +69,7 @@ Circuit Painter by passing it the file name:
 
     .. code:: python
 
-        painter = CircuitPainter('my_file.kicad_pcb')
+        p = CircuitPainter('my_file.kicad_pcb')
 
 New objects will then be added to that board, in a new group.
 

doc/concepts.rst

@@ -0,0 +1,76 @@
+Core concepts
+=============
+
+Circuit Painter works by drawing objects onto PCB layers.
+
+PCB layers
+----------
+
+There are a lot of layers that make up a PCB! Fortunately, we only need to
+focus on a few of them:
+
+* Edge cuts
+* Top silkscreen
+* Top soldermask
+* Top copper
+* Bottom copper
+* Bottom soldermask
+* Bottom silkscreen
+
+In Circuit Painter, you set the active drawing layer by calling the layer()
+function:
+
+    .. code:: python
+
+        painter.layer('F_Cu')
+
+Any objects created afterwards will be drawn on that layer, until it is
+updated by another layer() call. Note that some objects, particularly the
+conductive ones, can only be placed on a copper layer.
+
+Taxonomy of objects
+-------------------
+
+Circuit Painter allows you to create two categories of objects- conductive,
+and non-conductive. Conductive objects are used to carry electricity, and
+are assigned to 'nets'. Non-conductive objects are used for making graphics,
+markings, and defining the board outline.
+
+
+Conductive:
+
+* Tracks
+* Arc Tracks
+* Polygons
+* Footprints
+* Vias
+
+Non-Conductive:
+
+* Lines
+* Arcs
+* Cirles
+* Polygons
+* Rect
+* Text
+
+Object attribues
+----------------
+
+Many objects have attributes that need to be set when calling them. For
+example, the width of a line or track is set by the width() function.
+
+Global attributes are:
+
+* width
+* fill / no fill
+* layer
+* designators / no designators
+
+Drawing coordinates
+-------------------
+
+Circuit Painter features a virtual transformation matrix, to make scripting
+similar arrangements of objects anywhere on a board. It supports both linear
+and rotational transformations for all objects, allowing for example LEDs to
+be aligned around a circle.

doc/examples.rst

@@ -1,5 +1,5 @@
-Examples
-========
+Example Projects
+================
 
 Here is a collection of example boards designed using CircuitPainter.
 
@@ -29,4 +29,15 @@ Click on the photo to see the source code for the board.
          :width: 400
          :target: https://github.com/Blinkinlabs/circuitpainter/blob/main/examples/hello_painter.py
 
-        Hello Painter
+        Hello Painter
+
+    * - .. image:: _static/images/examples_perfboard.png
+         :width: 400
+         :target: https://github.com/Blinkinlabs/circuitpainter/blob/main/examples/perfboard.py
+
+        Perfboard
+
+      - 
+
+Have you made a board with Circuit Painter? Share it with us so that we can
+add it to the gallery!

doc/getting_started.rst

@@ -11,33 +11,33 @@ Start by creating a drawing context:
    .. code:: python
 
 		from circuitpainter import CircuitPainter
-		painter = CircuitPainter()
+		p = CircuitPainter()
 
 Using the painter object, you can draw non-conductive and conductve shapes,
 footprints, and text onto the PCB.
 
 First, set the layer to place the object on (tip: use
-print(painter.layers.keys()) to show all available layers):
+print(p.layers.keys()) to show all available layers):
 
 	.. code:: python
 
-		painter.layer('F_SilkS')
+		p.layer('F_SilkS')
 
 Next, draw some non-conductive objects:
 
 	.. code:: python
 
-		painter.circle(0,0,3) # Draw a circle with radius 3 at the board origin
-		painter.line(0,0,10,10) # Draw a line from the board origin to (10,10)
-		painter.circle(10,10,3) # Draw a circle with raidus 3 at position (10,10)
+		p.circle(0,0,3) # Draw a circle with radius 3 at the board origin
+		p.line(0,0,10,10) # Draw a line from the board origin to (10,10)
+		p.circle(10,10,3) # Draw a circle with raidus 3 at position (10,10)
 
 So far, there hasn't been any visual indication of what you're making.
 To get a preview of what your design looks like, use the preview()
 function:
 
 	.. code:: python
 	
-		painter.preview()
+		p.preview()
 
 This will save the design to a temporary location, then open it in the
 KiCad editor:
@@ -54,12 +54,12 @@ To change the width of lines, use the width() command:
 
 	.. code:: python
 
-		painter.width(0.5)
-		painter.line(0,0,10,0) # line with width 0.5mm
-		painter.width(1)
-		painter.line(0,5,10,5) # line with width 1mm
-		painter.width(2)
-		painter.line(0,10,10,10) # line with width 2mm
+		p.width(0.5)
+		p.line(0,0,10,0) # line with width 0.5mm
+		p.width(1)
+		p.line(0,5,10,5) # line with width 1mm
+		p.width(2)
+		p.line(0,10,10,10) # line with width 2mm
 
  .. image:: _static/images/example-line-widths.png
   :width: 600
@@ -69,9 +69,9 @@ translate() and rotate() features:
 
 	.. code:: python
 
-		painter.translate(10,10)
-		painter.rotate(30)
-		painter.rect(-5,-5,5,5) # Rectangle is drawn at a 30 degreen angle, centered at (10,10).
+		p.translate(10,10)
+		p.rotate(30)
+		p.rect(-5,-5,5,5) # Rectangle is drawn at a 30 degreen angle, centered at (10,10).
 
  .. image:: _static/images/example-rotate-rect.png
   :width: 600
@@ -81,12 +81,12 @@ calculated as a 2d transformation matrix)
 
 	.. code:: python
 
-		painter.translate(10,10)
-		painter.rect(-5,-5,5,5) # Rectangle is drawn centered at (10,10).
-		painter.translate(10,10)
-		painter.rect(-5,-5,5,5) # Rectangle is drawn centered at (20,20).
-		painter.translate(10,10)
-		painter.rect(-5,-5,5,5) # Rectangle is drawn centered at (30,30).
+		p.translate(10,10)
+		p.rect(-5,-5,5,5) # Rectangle is drawn centered at (10,10).
+		p.translate(10,10)
+		p.rect(-5,-5,5,5) # Rectangle is drawn centered at (20,20).
+		p.translate(10,10)
+		p.rect(-5,-5,5,5) # Rectangle is drawn centered at (30,30).
 
  .. image:: _static/images/example-translate-rect.png
   :width: 600
@@ -97,11 +97,11 @@ and pop_matrix(). (Note: This is implemented as a stack, and multiple pushes can
 	.. code:: python
 	
 		for angle in range(0,360,30):
-			painter.push_matrix() # Save the current transformation settings
-			painter.rotate(angle)
-			painter.translate(10,10)
-			painter.rect(-5,-5,5,5)
-			painter.pop_matrix() # Restore previous transformation settings
+			p.push_matrix() # Save the current transformation settings
+			p.rotate(angle)
+			p.translate(10,10)
+			p.rect(-5,-5,5,5)
+			p.pop_matrix() # Restore previous transformation settings
 
  .. image:: _static/images/example-push-pop-rect.png
   :width: 600
@@ -115,8 +115,8 @@ command:
 
 	.. code:: python
 	
-		painter.layer('F_Cu')
-		painter.footprint(0,0,"LED_SMD","LED_0805_2012Metric")
+		p.layer('F_Cu')
+		p.footprint(0,0,"LED_SMD","LED_0805_2012Metric")
 
  .. image:: _static/images/example-add-led.png
   :width: 600
@@ -129,10 +129,10 @@ your circuit is correct:
 
 	.. code:: python
 	
-		painter.layer('F_Cu')
-		painter.footprint(0,0,"Resistor_SMD","R_0805_2012Metric",nets=['gnd','led_n'])
-		painter.footprint(5,0,"LED_SMD","LED_0805_2012Metric",nets=['led_n','vcc'])
-		painter.track(1,0,4,0)
+		p.layer('F_Cu')
+		p.footprint(0,0,"Resistor_SMD","R_0805_2012Metric",nets=['gnd','led_n'])
+		p.footprint(5,0,"LED_SMD","LED_0805_2012Metric",nets=['led_n','vcc'])
+		p.track(1,0,4,0)
 
  .. image:: _static/images/example-connect-led.png
   :width: 600
@@ -153,15 +153,15 @@ the previous translation operations, to make a ring of LEDs:
 	.. code:: python
 
 		for angle in range(0,360,30):
-			painter.push_matrix()
-			painter.rotate(angle) # Rotation and translation for the next resistor/led combination
-			painter.translate(5,0)
-			painter.layer('F_Cu')
-			painter.footprint(0,0,"Resistor_SMD","R_0805_2012Metric",nets=['gnd',f'led_{angle}'])
-			painter.footprint(5,0,"LED_SMD","LED_0805_2012Metric",nets=[f'led_{angle}','vcc'])
-			painter.track(1,0,4,0)
-
-			painter.pop_matrix()
+			p.push_matrix()
+			p.rotate(angle) # Rotation and translation for the next resistor/led combination
+			p.translate(5,0)
+			p.layer('F_Cu')
+			p.footprint(0,0,"Resistor_SMD","R_0805_2012Metric",nets=['gnd',f'led_{angle}'])
+			p.footprint(5,0,"LED_SMD","LED_0805_2012Metric",nets=[f'led_{angle}','vcc'])
+			p.track(1,0,4,0)
+
+			p.pop_matrix()
   
  .. image:: _static/images/example-led-ring.png
   :width: 600
@@ -175,36 +175,36 @@ To make a complete board, here is the [rest of the owl](https://knowyourmeme.com
 		from circuitpainter import CircuitPainter
 		painter = CircuitPainter()
 		
-		painter.no_designators() # Don't show reference designator names on the board silkscreen
-		painter.layer('F_Cu')
-		painter.width(.2)
+		p.no_designators() # Don't show reference designator names on the board silkscreen
+		p.layer('F_Cu')
+		p.width(.2)
 		
 		for angle in range(0,360,36):
-			painter.push_matrix() # Save the current transformation settings
-			painter.rotate(angle)
-			painter.translate(5,0)
-			painter.footprint(0,0,"Resistor_SMD","R_0805_2012Metric",nets=['gnd',f'led_{angle}'])
-			painter.footprint(5,0,"LED_SMD","LED_0805_2012Metric",nets=[f'led_{angle}','vcc'])
-			painter.track(1,0,4,0) # Connect the resistor to the LED
-			painter.track(-1,0,-2,0) # Connect the resistor to ground
-			painter.via(-2,0)
-			painter.track(6,0,7,0) # Connect the LED to vcc
-			painter.via(7,0)
-			painter.pop_matrix()
+			p.push_matrix() # Save the current transformation settings
+			p.rotate(angle)
+			p.translate(5,0)
+			p.footprint(0,0,"Resistor_SMD","R_0805_2012Metric",nets=['gnd',f'led_{angle}'])
+			p.footprint(5,0,"LED_SMD","LED_0805_2012Metric",nets=[f'led_{angle}','vcc'])
+			p.track(1,0,4,0) # Connect the resistor to the LED
+			p.track(-1,0,-2,0) # Connect the resistor to ground
+			p.via(-2,0)
+			p.track(6,0,7,0) # Connect the LED to vcc
+			p.via(7,0)
+			p.pop_matrix()
 		
 		# Fill the back of the board with a copper zone, and assign it to the 'vcc' net
-		painter.layer('B_Cu')
-		painter.circle_zone(0,0,14,net='vcc')
+		p.layer('B_Cu')
+		p.circle_zone(0,0,14,net='vcc')
 		
 		# Add a battery connector to the back
-		painter.layer('B_Cu')
-		painter.footprint(0,0,"Battery","BatteryHolder_Keystone_3000_1x12mm",nets=['vcc','vcc','gnd'])
+		p.layer('B_Cu')
+		p.footprint(0,0,"Battery","BatteryHolder_Keystone_3000_1x12mm",nets=['vcc','vcc','gnd'])
 
 		# Make the board shape to a circle
-		painter.layer("Edge_Cuts")
-		painter.circle(0,0,14)
+		p.layer("Edge_Cuts")
+		p.circle(0,0,14)
 		
-		painter.preview()
+		p.preview()
 
  .. image:: _static/images/example-rest-of-owl.png
   :width: 600

doc/index.rst

@@ -24,6 +24,13 @@ Circuit painter works as a front end / wrapper for `KiCad's pcbnew <https://www.
 
 For more backgrond on the project, see `Matt's Hackaday Berlin talk <https://www.youtube.com/watch?v=9XV9PSsmMkk>`_ about Circuit painter.
 
+.. toctree::
+   :hidden:
+   :caption: Introduction
+
+   introduction
+   concepts
+
 .. toctree::
    :hidden:
    :caption: Getting Started