rewrite dh_python2.1, pycompile.1 and pyclean.1 manpages in ReStructured

Text, add quick guide for maintainers to dh_python2 manpage

Makefile

 #!/usr/bin/make -f
 INSTALL ?= install
 PREFIX ?= /usr/local
+MANPAGES ?= dh_python2.1 pycompile.1 pyclean.1
 
 clean:
 	make -C tests clean
 	make -C pydist clean
 	find . -name '*.py[co]' -delete
-	rm -f .coverage
+	rm -f .coverage $(MANPAGES)
 
 install-dev:
 	$(INSTALL) -m 755 -d $(DESTDIR)$(PREFIX)/bin \
@@ -26,6 +27,11 @@ install-runtime:
 
 install: install-dev install-runtime
 
+%.1: %.rst
+	rst2man $< > $@
+
+manpages: $(MANPAGES)
+
 dist_fallback:
 	make -C pydist $@
 

debian/changelog

@@ -10,7 +10,8 @@ python-defaults (2.6.6-11) UNRELEASED; urgency=low
     - --exclude now works with private dirs
     - use /usr/bin/pythonX.Y rather than pythonX.Y (to avoid /usr/local
       interpreters)
-    
+  * rewrite dh_python2.1, pycompile.1 and pyclean.1 manpages in ReStructured
+    Text, add quick guide for maintainers to dh_python2 manpage
 
  -- Piotr Ożarowski <piotr@debian.org>  Sat, 15 Jan 2011 21:14:38 +0100
 

debian/rules

@@ -149,7 +149,7 @@ stamp-dh_python:
 	dh_installdirs
 	make check_versions
 	DESTDIR=debian/python PREFIX=/usr make install-dev
-	DESTDIR=debian/python-minimal PREFIX=/usr make install-runtime
+	DESTDIR=debian/python-minimal PREFIX=/usr make install-runtime manpages
 	# disabled by default, run manually if you want to update it
 	# (requires apt-file and network connection)
 	#make -C pydist dist_fallback

dh_python2.1

-.TH DH_PYTHON2 "1" "August 2010" "dh_python2 2.0~beta1" "User Commands"
-.SH NAME
-dh_python2 \- calculates Python dependencies, adds maintainer scripts to byte compile files, etc.
-.SH SYNOPSIS
-.B dh_python2
-\fI-p PACKAGE \fR[\fI-V \fR[\fIX.Y\fR][\fI-\fR][\fIA.B\fR]] \fIDIR_OR_FILE \fR[\fI-X REGEXPR\fR]
-.SH OPTIONS
-.TP
-\fB\-\-version\fR
-show program's version number and exit
-.TP
-\fB\-h\fR, \fB\-\-help\fR
-show this help message and exit
-.TP
-\fB\-\-no\-guessing\-versions\fR
-disable guessing other supported Python versions
-.TP
-\fB\-\-no\-guessing\-deps\fR
-disable guessing dependencies
-.TP
-\fB\-\-skip\-private\fR
-don't check private directories
-.TP
-\fB\-v\fR, \fB\-\-verbose\fR
-turn verbose mode on
-.TP
-\fB\-i\fR, \fB\-\-indep\fR
-act on architecture independent packages
-.TP
-\fB\-a\fR, \fB\-\-arch\fR
-act on architecture dependent packages
-.TP
-\fB\-q\fR, \fB\-\-quiet\fR
-be quiet
-.TP
-\fB\-p\fR PACKAGE, \fB\-\-package\fR=\fIPACKAGE\fR
-act on the package named PACKAGE
-.TP
-\fB\-N\fR NO_PACKAGE, \fB\-\-no\-package\fR=\fINO_PACKAGE\fR
-do not act on the specified package
-.TP
-\fB\-V\fR VRANGE
-specify list of supported Python versions. See
-pycompile(1) for examples
-.TP
-\fB\-X\fR REGEXPR, \fB\-\-exclude\fR=\fIREGEXPR\fR
-exclude items that match given REGEXPR. You may use
-this option multiple times to build up a list of things
-to exclude.
-.TP
-\fB\-\-depends\fR=\fIDEPENDS\fR
-translate given requirements into Debian dependencies
-and add them to ${python:Depends}. Use it for missing
-items in requires.txt.
-.TP
-\fB\-\-recommends\fR=\fIRECOMMENDS\fR
-translate given requirements into Debian dependencies
-and add them to ${python:Recommends}
-.TP
-\fB\-\-suggests\fR=\fISUGGESTS\fR
-translate given requirements into Debian dependencies
-and add them to ${python:Suggests}
-.SH "SEE ALSO"
-/usr/share/doc/python-doc/README.PyDist (python-doc package)

dh_python2.rst

+============
+ dh_python2
+============
+
+-----------------------------------------------------------------------------------
+calculates Python dependencies, adds maintainer scripts to byte compile files, etc.
+-----------------------------------------------------------------------------------
+
+SYNOPSIS
+========
+  dh_python2 -p PACKAGE [-V [X.Y][-][A.B]] DIR_OR_FILE [-X REGEXPR]
+
+DESCRIPTION
+===========
+
+QUICK GUIDE FOR MAINTAINERS
+---------------------------
+
+ * if necessary, describe supported Python versions via X-Python-Version field
+   in debian/control,
+ * build-depend on python or python-all or python-all-dev (>= 2.6.6-3~),
+ * build module/application using its standard build system,
+   remember to build extensions for all supported Python versions (loop over
+   ``pyversions -vr``),
+ * install files to the *standard* locations, add ``--install-layout=deb`` to
+   setup.py's install command if your package is using distutils,
+ * add ``python2`` to dh's ``--with`` option, or:
+ * include /usr/share/cdbs/1/class/python-distutils.mk in debian/rules and
+   depend on cdbs (>= 0.4.90-1~), or:
+ * call dh_python2 in the binary-* target,
+ * add ${python:Depends} to Depends,
+ * add ${python:Breaks} to Breaks if your package provides public Python module
+   or extension
+
+NOTES
+-----
+
+In order to support more than one Python version in the same binary package,
+dh_python2 (unlike dh_pycentral and dh_pysupport) creates symlinks to all
+supported Python versions at build time. It means binNMU (or sourceful upload
+in case of architecture independent packages) are required once a list of
+supported Python version is changed. It's faster and more robust than its
+competitors, though.
+
+dh_python2 tries to translate Python dependencies from requires.txt file to
+Debian dependencies, use debian/pydist-overrides or --no-guessing-deps option
+to override it. If you want dh_python2 to generate more strict dependencies
+(f.e. to avoid ABI problems) create debian/python-foo.pydist file. See
+/usr/share/doc/python-doc/README.PyDist (provided by python-doc package) for
+more information.
+
+OPTIONS
+=======
+--version	show program's version number and exit
+
+-h, --help	show help message and exit
+
+--no-guessing-versions	disable guessing other supported Python versions
+
+--no-guessing-deps	disable guessing dependencies
+
+--skip-private	don't check private directories
+
+-v, --verbose	turn verbose mode on
+
+-i, --indep	act on architecture independent packages
+
+-a, --arch	act on architecture dependent packages
+
+-q, --quiet	be quiet
+
+-p PACKAGE, --package=PACKAGE	act on the package named PACKAGE
+
+-N NO_PACKAGE, --no-package=NO_PACKAGE	do not act on the specified package
+
+-V VRANGE	specify list of supported Python versions. See
+  pycompile(1) for examples
+
+-X REGEXPR, --exclude=REGEXPR	exclude items that match given REGEXPR. You may
+  use this option multiple times to build up a list of things to exclude.
+
+--depends=DEPENDS	translate given requirements into Debian dependencies
+  and add them to ${python:Depends}. Use it for missing items in requires.txt
+
+--recommends=RECOMMENDS		translate given requirements into Debian dependencies
+  and add them to ${python:Recommends}
+
+--suggests=SUGGESTS	translate given requirements into Debian dependencies
+  and add them to ${python:Suggests}
+
+SEE ALSO
+========
+* /usr/share/doc/python/python-policy.txt.gz
+* /usr/share/doc/python-doc/README.PyDist (python-doc package)
+* pycompile(1), pyclean(1)
+* dh_python3(1), py3compile(1), py3clean(1)
+* Wiki page about converting python-support based package to dh_python2:
+  http://wiki.debian.org/Python/support2dhp2

pyclean.1

-.TH PYCLEAN "1" "August 2010" "pyclean 0.9" "User Commands"
-.SH NAME
-pyclean \- removes .pyc and .pyo files
-.SH SYNOPSIS
-.B pyclean
-[\fI-p PACKAGE | DIR_OR_FILE\fR]
-.SH OPTIONS
-.TP
-\fB\-\-version\fR
-show program's version number and exit
-.TP
-\fB\-h\fR, \fB\-\-help\fR
-show this help message and exit
-.TP
-\fB\-v\fR, \fB\-\-verbose\fR
-turn verbose more one
-.TP
-\fB\-q\fR, \fB\-\-quiet\fR
-be quiet
-.TP
-\fB\-p\fR PACKAGE, \fB\-\-package\fR=\fIPACKAGE\fR
-specify Debian package name to clean

pyclean.rst

+=========
+ pyclean
+=========
+
+---------------------------
+removes .pyc and .pyo files
+---------------------------
+
+SYNOPSIS
+========
+  pyclean [-p PACKAGE | DIR_OR_FILE]
+
+OPTIONS
+=======
+--version	show program's version number and exit
+
+-h, --help	show this help message and exit
+
+-v, --verbose	turn verbose more one
+
+-q, --quiet	be quiet
+
+-p PACKAGE, --package=PACKAGE	specify Debian package name to clean

pycompile.1

-.TH PYCOMPILE "1" "August 2010" "pycompile 0.9" "User Commands"
-.SH NAME
-pycompile \- byte compile Python source files
-.SH SYNOPSIS
-.B pycompile
-[\fI-V \fR[\fIX.Y\fR][\fI-\fR][\fIA.B\fR]] \fIDIR_OR_FILE \fR[\fI-X REGEXPR\fR]
-.P
-.B pycompile
-\fB\-p\fR PACKAGE
-.SH DESCRIPTION
-Wrapper around
-.B py_compile
-to byte-compile python files.
-.SH OPTIONS
-.TP
-\fB\-\-version\fR
-Show program's version number and exit.
-.TP
-\fB\-h\fR, \fB\-\-help\fR
-Show this help message and exit
-.TP
-\fB\-f\fR, \fB\-\-force\fR
-Force rebuild of byte-code files even if timestamps are up-to-date.
-.TP
-\fB\-O\fR
-Byte-compile to .pyo files.
-.TP
-\fB\-q\fR, \fB\-\-quiet\fR
-Be quiet.
-.TP
-\fB\-v\fR, \fB\-\-verbose\fR
-Turn verbose mode on.
-.TP
-\fB\-p\fR PACKAGE, \fB\-\-package\fR=\fIPACKAGE\fR
-Specify Debian package name whose files should be
-bytecompiled.
-.TP
-\fB\-V\fR VRANGE
-Force private modules to be bytecompiled with Python
-version from given range, regardless of the default
-Python version in the system. If there are no other
-options, bytecompile all public modules for installed
-Python versions that match given range.  VERSION_RANGE
-examples: '2.5' (version 2.5 only), '2.5\-' (version
-2.5 or newer), '2.5\-2.7' (version 2.5 or 2.6), '\-3.0'
-(all supported 2.X versions).
-.TP
-\fB\-X\fR REGEXPR, \fB\-\-exclude\fR=\fIREGEXPR\fR
-exclude items that match given REGEXPR. You may use
-this option multiple times to build up a list of
-things to exclude.

pycompile.rst

+==========
+ pycompile
+==========
+
+--------------------------------
+byte compile Python source files
+--------------------------------
+
+SYNOPSIS
+========
+  pycompile [-V [X.Y][-][A.B]] DIR_OR_FILE [-X REGEXPR]
+
+  pycompile -p PACKAGE
+
+DESCRIPTION
+===========
+Wrapper around Python standard library's py_compile module to byte-compile
+Python files.
+
+OPTIONS
+=======
+--version	show program's version number and exit
+
+-h, --help	show this help message and exit
+
+-f, --force	force rebuild of byte-code files even if timestamps are up-to-date
+
+-O		byte-compile to .pyo files
+
+-q, --quiet	be quiet
+
+-v, --verbose	turn verbose mode on
+
+-p PACKAGE, --package=PACKAGE	specify Debian package name whose files should
+  be bytecompiled
+
+-V VRANGE	force private modules to be bytecompiled with Python
+  version from given range, regardless of the default Python version in the
+  system. If there are no other options, bytecompile all public modules
+  for installed Python versions that match given range. VERSION_RANGE examples:
+
+   * ``2.5``	version 2.5 only
+   * ``2.5-``	version 2.5 or newer
+   * ``2.5-2.7``	version 2.5 or 2.6
+   * ``-3.0``	all supported 2.X versions
+
+-X REGEXPR, --exclude=REGEXPR	exclude items that match given REGEXPR. You may
+  use this option multiple times to build up a list of things to exclude