Turn pinout docs into man-page

Stops lintian whinging about missing man-pages

.gitignore

@@ -30,3 +30,4 @@ coverage
 
 # Generated documentation
 docs/_build
+man/

Makefile

@@ -55,7 +55,7 @@ DIST_DEB=dist/python-$(NAME)_$(VER)$(DEB_SUFFIX)_all.deb \
 DIST_DSC=dist/$(NAME)_$(VER)$(DEB_SUFFIX).tar.gz \
 	dist/$(NAME)_$(VER)$(DEB_SUFFIX).dsc \
 	dist/$(NAME)_$(VER)$(DEB_SUFFIX)_source.changes
-MAN_PAGES=
+MAN_PAGES=man/pinout.1 man/remote-gpio.7
 
 
 # Default target

debian/rules

@@ -10,6 +10,8 @@ export DH_OPTIONS
 override_dh_auto_install:
 	python setup.py install --root debian/python-gpiozero --install-layout=deb
 	python3 setup.py install --root debian/python3-gpiozero --install-layout=deb
+	# Strip out binaries from the py2 package
+	rm debian/python-gpiozero/usr/bin/pinout
 
 #override_dh_auto_test:
 #	# Don't run the tests!

docs/api_pins.rst

@@ -31,6 +31,8 @@ default factory can be constructed (e.g. because no GPIO implementations are
 installed, or all of them fail to load for whatever reason), an
 :exc:`ImportError` will be raised.
 
+.. _changing-pin-factory:
+
 Changing the pin factory
 ========================
 

docs/changelog.rst

@@ -5,7 +5,7 @@ Changelog
 .. currentmodule:: gpiozero
 
 
-Release 1.4.0 (2017-07-16)
+Release 1.4.0 (2017-07-??)
 ==========================
 
 * Pin factory is now :ref:`configurable from device constructors

docs/cli_pinout.rst

@@ -0,0 +1,171 @@
+pinout
+======
+
+Synopsis
+--------
+
+::
+
+    pinout [-h] [-r REVISION] [-c] [-m]
+
+Description
+-----------
+
+A utility for querying Raspberry Pi GPIO pin-out information. Running
+:program:`pinout` on its own will output a board diagram, and GPIO header
+diagram for the current Raspberry Pi. It is also possible to manually specify a
+revision of Pi, or (by using :doc:`remote_gpio`) to output information about a
+remote Pi.
+
+Options
+-------
+
+.. program:: pinout
+
+.. option:: -h, --help
+
+    show this help message and exit
+
+.. option:: -r REVISION, --revision REVISION
+
+    RPi revision. Default is to autodetect revision of current device
+
+.. option:: -c, --color
+
+    Force colored output (by default, the output will include ANSI color codes
+    if run in a color-capable terminal). See also :option:`--monochrome`
+
+.. option:: -m, --monochrome
+
+    Force monochrome output. See also :option:`--color`
+
+Examples
+--------
+
+To output information about the current Raspberry Pi:
+
+.. code-block:: console
+
+    $ pinout
+
+For a Raspberry Pi model 2B, this will output something like the following:
+
+.. code-block:: none
+
+    ,--------------------------------.
+    | oooooooooooooooooooo J8     +====
+    | 1ooooooooooooooooooo        | USB
+    |                             +====
+    |      Pi Model 2B V1.1          |
+    |      +----+                 +====
+    | |D|  |SoC |                 | USB
+    | |S|  |    |                 +====
+    | |I|  +----+                    |
+    |                   |C|     +======
+    |                   |S|     |   Net
+    | pwr        |HDMI| |I||A|  +======
+    `-| |--------|    |----|V|-------'
+
+    Revision           : a01041
+    SoC                : BCM2836
+    RAM                : 1024Mb
+    Storage            : MicroSD
+    USB ports          : 4 (excluding power)
+    Ethernet ports     : 1
+    Wi-fi              : False
+    Bluetooth          : False
+    Camera ports (CSI) : 1
+    Display ports (DSI): 1
+
+    J8:
+       3V3  (1) (2)  5V
+     GPIO2  (3) (4)  5V
+     GPIO3  (5) (6)  GND
+     GPIO4  (7) (8)  GPIO14
+       GND  (9) (10) GPIO15
+    GPIO17 (11) (12) GPIO18
+    GPIO27 (13) (14) GND
+    GPIO22 (15) (16) GPIO23
+       3V3 (17) (18) GPIO24
+    GPIO10 (19) (20) GND
+     GPIO9 (21) (22) GPIO25
+    GPIO11 (23) (24) GPIO8
+       GND (25) (26) GPIO7
+     GPIO0 (27) (28) GPIO1
+     GPIO5 (29) (30) GND
+     GPIO6 (31) (32) GPIO12
+    GPIO13 (33) (34) GND
+    GPIO19 (35) (36) GPIO16
+    GPIO26 (37) (38) GPIO20
+       GND (39) (40) GPIO21
+
+By default, if stdout is a console that supports color, ANSI codes will be used
+to produce color output. Output can be forced to be :option:`--monochrome`:
+
+.. code-block:: console
+
+    $ pinout --monochrome
+
+Or forced to be :option:`--color`, in case you are redirecting to something
+capable of supporting ANSI codes:
+
+.. code-block:: console
+
+    $ pinout --color | less -SR
+
+To manually specify the revision of Pi you want to query, use
+:option:`--revision`. The tool understands both old-style `revision codes`_
+(such as for the model B):
+
+.. code-block:: console
+
+    $ pinout -r 000d
+
+Or new-style `revision codes`_ (such as for the Pi Zero):
+
+.. code-block:: console
+
+    $ pinout -r 900093
+
+You can also use the tool with :doc:`remote_gpio` to query remote Raspberry
+Pi's:
+
+.. code-block:: console
+
+    $ GPIOZERO_PIN_FACTORY=pigpio PIGPIO_ADDR=other_pi pinout
+
+Or run the tool directly on a PC using the mock pin implementation (although in
+this case you'll almost certainly want to specify the Pi revision manually):
+
+.. code-block:: console
+
+    $ GPIOZERO_PIN_FACTORY=mock pinout -r a22042
+
+Environment Variables
+---------------------
+
+GPIOZERO_PIN_FACTORY
+    The library to use when communicating with the GPIO pins. Defaults to
+    attempting to load RPi.GPIO, then RPIO, then pigpio, and finally uses a
+    native Python implementation. Valid values include "rpigpio", "rpio",
+    "pigpio", "native", and "mock". The latter is most useful on non-Pi
+    platforms as it emulates a Raspberry Pi model 3B (by default).
+
+PIGPIO_ADDR
+    The hostname of the Raspberry Pi the pigpio library should attempt to
+    connect to (if the pigpio pin factory is being used). Defaults to
+    ``localhost``.
+
+PIGPIO_PORT
+    The port number the pigpio library should attempt to connect to (if the
+    pigpio pin factory is being used). Defaults to 8888.
+
+
+.. only:: builder_man
+
+    See Also
+    --------
+
+        :manpage:`remote-gpio(7)`
+
+.. _revision codes: http://elinux.org/RPi_HardwareHistory

docs/cli_tools.rst

@@ -2,25 +2,8 @@
 Command-line Tools
 ==================
 
-Pinout
-======
-
 The gpiozero package contains a database of information about the various
-revisions of Raspberry Pi. This is queried by the ``pinout`` command-line
+revisions of Raspberry Pi. This is queried by the :program:`pinout`
-tool to output details of the GPIO pins available.
+command-line tool to output details of the GPIO pins available.
 
-Unless specified, the revision of the current device will be detected. A
+.. include:: cli_pinout.rst
-particular revision may be selected with the --revision command-line
-option. For example::
-
-    pinout --revision 000d
-
-By default, the output will include ANSI color codes if run in a color-capable
-terminal. This behaviour may be overridden by the --color or --monochrome
-options to force colored or non-colored output, respectively. For example::
-
-    pinout --monochrome
-
-Full usage details are available with::
-
-    pinout --help

docs/conf.py

@@ -153,9 +153,12 @@ epub_show_urls = 'no'
 
 # -- Options for manual page output ---------------------------------------
 
-man_pages = []
+man_pages = [
+    ('cli_pinout',  'pinout',      'GPIO Zero pinout tool',       [_setup.__author__], 1),
+    ('remote_gpio', 'remote-gpio', 'GPIO Zero remote GPIO guide', [_setup.__author__], 7),
+]
 
-#man_show_urls = False
+man_show_urls = True
 
 # -- Options for Texinfo output -------------------------------------------