From 1063f88b37938282e80cf5d5f11dc80ea183fd3c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Piotr=20O=C5=BCarowski?= <piotr@debian.org>
Date: Sun, 6 Feb 2011 21:20:41 +0100
Subject: [PATCH] rewrite dh_python2.1, pycompile.1 and pyclean.1 manpages in
ReStructured Text, add quick guide for maintainers to dh_python2 manpage
---
Makefile | 8 +++-
debian/changelog | 3 +-
debian/rules | 2 +-
dh_python2.1 | 64 -------------------------------
dh_python2.rst | 98 ++++++++++++++++++++++++++++++++++++++++++++++++
pyclean.1 | 22 -----------
pyclean.rst | 23 ++++++++++++
pycompile.1 | 51 -------------------------
pycompile.rst | 48 ++++++++++++++++++++++++
9 files changed, 179 insertions(+), 140 deletions(-)
delete mode 100644 dh_python2.1
create mode 100644 dh_python2.rst
delete mode 100644 pyclean.1
create mode 100644 pyclean.rst
delete mode 100644 pycompile.1
create mode 100644 pycompile.rst
diff --git a/Makefile b/Makefile
index 8b94732..6b5be1e 100644
--- a/Makefile
+++ b/Makefile
@@ -1,12 +1,13 @@
#!/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 $@
diff --git a/debian/changelog b/debian/changelog
index ed2af22..0abde32 100644
--- a/debian/changelog
+++ b/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
diff --git a/debian/rules b/debian/rules
index 30d5f5a..0165808 100755
--- a/debian/rules
+++ b/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
diff --git a/dh_python2.1 b/dh_python2.1
deleted file mode 100644
index 338e0b3..0000000
--- a/dh_python2.1
+++ /dev/null
@@ -1,64 +0,0 @@
-.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)
diff --git a/dh_python2.rst b/dh_python2.rst
new file mode 100644
index 0000000..624e8aa
--- /dev/null
+++ b/dh_python2.rst
@@ -0,0 +1,98 @@
+============
+ 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
diff --git a/pyclean.1 b/pyclean.1
deleted file mode 100644
index 2cdfdbb..0000000
--- a/pyclean.1
+++ /dev/null
@@ -1,22 +0,0 @@
-.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
diff --git a/pyclean.rst b/pyclean.rst
new file mode 100644
index 0000000..435ef40
--- /dev/null
+++ b/pyclean.rst
@@ -0,0 +1,23 @@
+=========
+ 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
diff --git a/pycompile.1 b/pycompile.1
deleted file mode 100644
index 16812bf..0000000
--- a/pycompile.1
+++ /dev/null
@@ -1,51 +0,0 @@
-.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.
diff --git a/pycompile.rst b/pycompile.rst
new file mode 100644
index 0000000..e59fdcf
--- /dev/null
+++ b/pycompile.rst
@@ -0,0 +1,48 @@
+==========
+ 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
--
GitLab