Automatically embed usage in readme (easier to keep up to date :)

Makefile

@@ -1,7 +1,7 @@
 # Makefile for deb-pkg-tools.
 #
 # Author: Peter Odding <peter@peterodding.com>
-# Last Change: June 9, 2014
+# Last Change: July 16, 2015
 # URL: https://github.com/xolox/python-deb-pkg-tools
 
 WORKON_HOME ?= $(HOME)/.virtualenvs
@@ -52,6 +52,10 @@ clean:
 	find -depth -type d -name __pycache__ -exec rm -Rf {} \;
 	find -type f -name '*.pyc' -delete
 
+readme:
+	test -x "$(VIRTUAL_ENV)/bin/cog.py" || ($(ACTIVATE) && pip-accel install cogapp)
+	$(ACTIVATE) && cog.py -r README.rst
+
 docs: install
 	test -x "$(VIRTUAL_ENV)/bin/sphinx-build" || ($(ACTIVATE) && pip-accel install sphinx)
 	cd docs && make html

README.rst

@@ -39,26 +39,68 @@ You can install the `deb-pkg-tools` package using the following command::
 
     $ pip install deb-pkg-tools
 
-After installation you'll have the ``deb-pkg-tools`` program available::
-
-    $ deb-pkg-tools --help
-    Usage: deb-pkg-tools [OPTIONS]
-
-    Supported options:
-
-      -i, --inspect=FILE          inspect the metadata in a *.deb archive
-      -b, --build=DIR             build a Debian package with `dpkg-deb --build'
-      -u, --update-repo=DIR       create/update a trivial package repository
-      -a, --activate-repo=DIR     enable `apt-get' to install packages from a
-                                  trivial repository (requires root/sudo privilege)
-      -d, --deactivate-repo=DIR   cleans up after --activate-repo
-                                  (requires root/sudo privilege)
-      -w, --with-repo=DIR CMD...  create/update a trivial package repository,
-                                  activate the repository, run the positional
-                                  arguments as an external command (usually `apt-get
-                                  install') and finally deactivate the repository
-      -v, --verbose               make more noise
-      -h, --help                  show this message and exit
+After installation you'll have the ``deb-pkg-tools`` program available:
+
+.. A DRY solution to avoid duplication of the `deb-pkg-tools --help' text:
+..
+.. [[[cog
+.. from humanfriendly.usage import inject_usage
+.. inject_usage('deb_pkg_tools.cli')
+.. ]]]
+
+**Usage:** `deb-pkg-tools [OPTIONS] ...`
+
+Wrapper for the deb-pkg-tools Python project that implements various tools to inspect, build and manipulate Debian binary package archives and related entities like trivial repositories.
+
+**Supported options:**
+
+.. csv-table::
+   :header: Option, Description
+   :widths: 30, 70
+
+
+   "``-i``, ``--inspect=FILE``","Inspect the metadata in the Debian binary package archive given by ``FILE``.
+   "
+   "``-c``, ``--collect=DIR``","Copy the package archive(s) given as positional arguments (and all packages
+   archives required by the given package archives) into the directory given
+   by ``DIR``.
+   "
+   "``-C``, ``--check=FILE``","Perform static analysis on a package archive and its dependencies in order
+   to recognize common errors as soon as possible.
+   "
+   "``-p``, ``--patch=FILE``","Patch fields into the existing control file given by ``FILE``. To be used
+   together with the ``-s``, ``--set`` option.
+   "
+   "``-s``, ``--set=LINE``","A line to patch into the control file (syntax: ""Name: Value""). To be used
+   together with the ``-p``, ``--patch`` option.
+   "
+   "``-b``, ``--build=DIR``","Build a Debian binary package with ""dpkg-deb ``--build``"" (and lots of
+   intermediate Python magic, refer to the API documentation of the project
+   for full details) based on the binary package template in the directory
+   given by ``DIR``.
+   "
+   "``-u``, ``--update-repo=DIR``","Create or update the trivial Debian binary package repository in the
+   directory given by ``DIR``.
+   "
+   "``-a``, ``--activate-repo=DIR``","Enable ""apt-get"" to install packages from the trivial repository (requires
+   root/sudo privilege) in the directory given by ``DIR``. Alternatively you can
+   use the ``-w``, ``--with-repo`` option.
+   "
+   "``-d``, ``--deactivate-repo=DIR``","Cleans up after ``--activate-repo`` (requires root/sudo privilege).
+   Alternatively you can use the ``-w``, ``--with-repo`` option.
+   "
+   "``-w``, ``--with-repo=DIR`` CMD...","Create or update a trivial package repository, activate the repository, run
+   the positional arguments as an external command (usually ""apt-get install"")
+   and finally deactivate the repository.
+   "
+   "``-y``, ``--yes``","Assume the answer to interactive questions is yes.
+   "
+   "``-v``, ``--verbose``","Make more noise! (useful during debugging)
+   "
+   "``-h``, ``--help``","Show this message and exit.
+   "
+
+.. [[[end]]]
 
 One thing to note is that the operation of ``deb-pkg-tools --update-repo`` can
 be influenced by a configuration file. For details about this, please refer to

deb_pkg_tools/__init__.py

@@ -5,7 +5,7 @@
 # URL: https://github.com/xolox/python-deb-pkg-tools
 
 # Semi-standard module versioning.
-__version__ = '1.33'
+__version__ = '1.34'
 
 debian_package_dependencies = (
     'apt',        # apt-get

deb_pkg_tools/cli.py

@@ -1,37 +1,83 @@
 # Debian packaging tools: Command line interface
 #
 # Author: Peter Odding <peter@peterodding.com>
-# Last Change: August 31, 2014
+# Last Change: July 16, 2015
 # URL: https://github.com/xolox/python-deb-pkg-tools
 
 """
 Usage: deb-pkg-tools [OPTIONS] ...
 
+Wrapper for the deb-pkg-tools Python project that implements various tools to
+inspect, build and manipulate Debian binary package archives and related
+entities like trivial repositories.
+
 Supported options:
 
-  -i, --inspect=FILE          inspect the metadata in a *.deb archive
-  -c, --collect=DIR           copy the package archive(s) given as positional
-                              arguments and all packages archives required by
-                              the given package archives into a directory
-  -C, --check=FILE            perform static analysis on a package archive and
-                              its dependencies in order to recognize common
-                              errors as soon as possible
-  -p, --patch=FILE            patch fields into an existing control file
-  -s, --set=LINE              a line to patch into the control file
-                              (syntax: "Name: Value")
-  -b, --build=DIR             build a Debian package with `dpkg-deb --build'
-  -u, --update-repo=DIR       create/update a trivial package repository
-  -a, --activate-repo=DIR     enable `apt-get' to install packages from a
-                              trivial repository (requires root/sudo privilege)
-  -d, --deactivate-repo=DIR   cleans up after --activate-repo
-                              (requires root/sudo privilege)
-  -w, --with-repo=DIR CMD...  create/update a trivial package repository,
-                              activate the repository, run the positional
-                              arguments as an external command (usually `apt-get
-                              install') and finally deactivate the repository
-  -y, --yes                   assume the answer to interactive questions is yes
-  -v, --verbose               make more noise
-  -h, --help                  show this message and exit
+  -i, --inspect=FILE
+
+    Inspect the metadata in the Debian binary package archive given by FILE.
+
+  -c, --collect=DIR
+
+    Copy the package archive(s) given as positional arguments (and all packages
+    archives required by the given package archives) into the directory given
+    by DIR.
+
+  -C, --check=FILE
+
+    Perform static analysis on a package archive and its dependencies in order
+    to recognize common errors as soon as possible.
+
+  -p, --patch=FILE
+
+    Patch fields into the existing control file given by FILE. To be used
+    together with the -s, --set option.
+
+  -s, --set=LINE
+
+    A line to patch into the control file (syntax: "Name: Value"). To be used
+    together with the -p, --patch option.
+
+  -b, --build=DIR
+
+    Build a Debian binary package with `dpkg-deb --build' (and lots of
+    intermediate Python magic, refer to the API documentation of the project
+    for full details) based on the binary package template in the directory
+    given by DIR.
+
+  -u, --update-repo=DIR
+
+    Create or update the trivial Debian binary package repository in the
+    directory given by DIR.
+
+  -a, --activate-repo=DIR
+
+    Enable `apt-get' to install packages from the trivial repository (requires
+    root/sudo privilege) in the directory given by DIR. Alternatively you can
+    use the -w, --with-repo option.
+
+  -d, --deactivate-repo=DIR
+
+    Cleans up after --activate-repo (requires root/sudo privilege).
+    Alternatively you can use the -w, --with-repo option.
+
+  -w, --with-repo=DIR
+
+    Create or update a trivial package repository, activate the repository, run
+    the positional arguments as an external command (usually `apt-get install')
+    and finally deactivate the repository.
+
+  -y, --yes
+
+    Assume the answer to interactive questions is yes.
+
+  -v, --verbose
+
+    Make more noise! (useful during debugging)
+
+  -h, --help
+
+    Show this message and exit.
 """
 
 # Standard library modules.

requirements.txt

@@ -2,7 +2,7 @@
 cached-property >= 0.1.5
 coloredlogs >= 0.4.6
 executor >= 1.3
-humanfriendly >= 1.11
+humanfriendly >= 1.31
 python-debian >= 0.1.21-nmu2
 # Undocumented transitive dependency of python-debian...
 chardet