start generating example documentation with code-guide (http://github…

….com/npryce/code-guide)

Makefile

@@ -19,6 +19,8 @@ PIP=$(PYTHON_EXE) $(PYTHON_ENV)/bin/pip
 PROJECT:=$(shell $(PYTHON_EXE) setup.py --name)
 VERSION:=$(shell $(PYTHON_EXE) setup.py --version)
 
+EXAMPLES:=$(wildcard examples/*)
+EXAMPLE_DOCS:=$(EXAMPLES:%=docs/%.html)
 
 all: check dist
 .PHONY: all
@@ -65,8 +67,19 @@ dist/$(PROJECT)-$(VERSION).tar.gz: setup.py Makefile README.rst
 dist: dist/$(PROJECT)-$(VERSION).tar.gz
 .PHONY: dist
 
+docs: $(EXAMPLE_DOCS) docs/examples/code-guide.css
+.PHONY: docs
+
+docs/examples/%.html: examples/%
+	@mkdir -p $(dir $@)
+	code-guide $< -o $@ -r . -l python -c "#" -t '(.+)' '\1.html'
+
+docs/examples/code-guide.css:
+	@mkdir -p $(dir $@)
+	code-guide --extract-resources --resource-dir=$(dir $@)
+
 clean:
-	rm -rf output/ dist/ build/ MANIFEST README.rst quick2wire_api.egg-info README.rst
+	rm -rf output/ dist/ build/ docs/ MANIFEST README.rst quick2wire_api.egg-info README.rst
 	find . -name '*.pyc' -o -name '*~' | xargs -r rm -f
 .PHONY: clean
 

examples/blink

@@ -1,16 +1,68 @@
 #!/usr/bin/env python3
+#|| Blink
+#|| =====
+#||
+#|| Let's start by blinking the LED on the Quick2Wire interface board.
+#||
+#|| The Raspberry Pi's header has 8 pins reserved for GPIO, numbered 0
+#|| to 7. The Quick2Wire interface board breaks these pins out to
+#|| their own header and clearly labels them on the board.  Pin 1 can
+#|| be jumpered to the on-board LED, so you can flash an LED without
+#|| having to do any additional wiring.
+#||
+#|| In the Quick2Wire API, software controls a physical GPIO pin via a
+#|| _Pin_ object. A Pin has a _direction_ (In or Out) and a _value_ (1
+#|| or 0) that can be read (if the Pin has direction In) or written
+#|| (if the Pin has direction Out).
+#||
+#|| A program gets hold of a Pin object from a _PinBank_, which
+#|| represents a collection of related pins indexed by pin number.
+#|| The Quick2Wire API defines a PinBank for the Pi's 8 GPIO pins,
+#|| called simply "pins".  It also defines PinBanks for the Pi's
+#|| header, indexed by header pin number 0 to 26 and by the pin
+#|| numbers defined by the Broadcom SoC.  The latter two are not used
+#|| in this demo, so we'll talk of them no more.
+#||
+#|| Here's how to use a Pin to blink an LED.
 
+#| [6] To make Python happy we need to import `pins` and `Out` from
+#| the Quick2Wire GPIO module and the other functions we've used from
+#| Python's standard library modules.
+from quick2wire.gpio import pins, Out
 from itertools import cycle
 from time import sleep
-from quick2wire.gpio import pins, Out
+#|.
 
+#| [1] To get a Pin object to control the on-board LED we ask the
+#| _pins_ PinBank for pin 1, specifying that we want to use it for
+#| output by passing `Out ` as the _direction_ parameter.
 led = pins.pin(1, direction=Out)
+#|.
 
-led_state = 1
-
+#| [5] A program must open the pin before it can set its value and
+#| close the pin when you no longer need it.  While we have an open
+#| pin, other processes running on the Pi cannot use the same pin and
+#| interfere with our I/O.  The most convenient way to do this is to
+#| use Python's `with` statement, which will open the pins at the
+#| start of the statement and close them when the body of the
+#| statement has finished running, even if the user kills the program
+#| or a failure makes the code throw an exception.
 with led:
+#|.
+    #| [2] The program loops forever.  Each time round the loop the
+    #| variable _v_ cycles between 1 and 0.
     for v in cycle([1,0]):
+    #|.
+        #| [3] Each time round the loop sets the value of the led Pin
+        #| to _v_, which either turns the LED on (when _v_ is 1) or
+        #| off (when _v_ is 0).
         led.value = v
+        #|.
+        #| [4] After setting the value of the LED, the program sleeps
+        #| for half a second, making the LED blink with a frequency of
+        #| 1Hz.
         sleep(0.5)
+        #|.
 
-
+#|| The next example, [button-blink](button-blink), shows how to also
+#|| read the state of a GPIO input pin connected to a push-button.

examples/button-blink

@@ -1,15 +1,44 @@
 #!/usr/bin/env python3
+#|| Button Blink
+#|| ============
+#|| 
+#|| This program adds user-input to the [blink](blink) program.  The
+#|| LED only blinks while the user holds down the push-button on the
+#|| Quick2Wire interface board. The push-button is connected to GPIO
+#|| pin P0 by a jumper.
 
+#| [2] The program needs to import the `In` constant from the quick2wire.gpio module.
+from quick2wire.gpio import pins, In, Out
+#|.
 from itertools import cycle
 from time import sleep
-from quick2wire.gpio import pins, In, Out
 
+#| [1] To read input from GPIO pin P0 the program also gets hold of pin 0
+#| for input by passing the `In` as the direction parameter.
 button = pins.pin(0, direction=In)
+#|.
 led = pins.pin(1, direction=Out)
 
+#| [3] The program must open both pins before using them.
 with button, led:
-    print("ready")
-
+#|.
     for v in cycle([1,0]):
-        led.value = v and button.value
+        #| [4] Within the loop the value property of the _led_ pin is
+        #| set to _v_ multiplied by the value property of the _button_
+        #| pin. When the button is pressed, button.value = 1, and
+        #| therefore led.value = v * 1 = v, which the main loop cycles
+        #| between 0 and 1.  When the button is released, button.value
+        #| = 0 and therefore led.value = v * 0 = 0.  As a result the
+        #| LED blinks while the button is pressed and stays off while
+        #| the button is released.
+        led.value = v * button.value
+        #|.
         sleep(0.5)
+
+#|| However, there's a flaw in this program. If you repeatedly press
+#|| and release the button you can see that the program can take up to
+#|| half a second to react. The program should react to the button
+#|| immediately. To do so it must handle GPIO interrupts in an _event
+#|| loop_. That's what we'll look at in the 
+#|| [selector-button-blink](selector-button-blink) example.
+