From afa23949e8aa56c5fe4e52a6100a232cddabb205 Mon Sep 17 00:00:00 2001 From: Dave Jones Date: Sun, 16 Jul 2017 20:45:34 +0100 Subject: [PATCH] Turn pinout docs into man-page Stops lintian whinging about missing man-pages --- .gitignore | 1 + Makefile | 2 +- debian/rules | 2 + docs/api_pins.rst | 2 + docs/changelog.rst | 2 +- docs/cli_pinout.rst | 171 ++++++++++++++++++++++++++++++++++++++++++++ docs/cli_tools.rst | 23 +----- docs/conf.py | 7 +- 8 files changed, 186 insertions(+), 24 deletions(-) create mode 100644 docs/cli_pinout.rst diff --git a/.gitignore b/.gitignore index 583b828..54cf950 100644 --- a/.gitignore +++ b/.gitignore @@ -30,3 +30,4 @@ coverage # Generated documentation docs/_build +man/ diff --git a/Makefile b/Makefile index 4d7961c..000256b 100644 --- a/Makefile +++ b/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 diff --git a/debian/rules b/debian/rules index 0f66107..00f3387 100755 --- a/debian/rules +++ b/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! diff --git a/docs/api_pins.rst b/docs/api_pins.rst index e15017f..bec1dae 100644 --- a/docs/api_pins.rst +++ b/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 ======================== diff --git a/docs/changelog.rst b/docs/changelog.rst index fbd3016..a87c771 100644 --- a/docs/changelog.rst +++ b/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 diff --git a/docs/cli_pinout.rst b/docs/cli_pinout.rst new file mode 100644 index 0000000..1a1686e --- /dev/null +++ b/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 diff --git a/docs/cli_tools.rst b/docs/cli_tools.rst index 1b1443d..757d7d2 100644 --- a/docs/cli_tools.rst +++ b/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 -tool to output details of the GPIO pins available. +revisions of Raspberry Pi. This is queried by the :program:`pinout` +command-line tool to output details of the GPIO pins available. -Unless specified, the revision of the current device will be detected. A -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 +.. include:: cli_pinout.rst diff --git a/docs/conf.py b/docs/conf.py index fbbe280..ce35da0 100644 --- a/docs/conf.py +++ b/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 -------------------------------------------