Update dh_auto documentation.

* dh_auto.pod -> dh_auto.7 - contains general information about dh_auto,
  its features, build systems supported by default (the latter is injected by
  man/dh_auto_pod script from Debian/Debhelper/Buildsystem/*.pm PODs via
  placeholders (#PLACEHOLDER#))
* POD in Debian/Debhelper/Buildsystem/*.pm -> dh_auto_<buildsystem>.7 - build
  system specific information.
* dh_auto_* -> dh_auto_*.1 - relatively shorty description of the specific
  dh_auto_* program and build system specific info for that step injected from
  Debian/Debhelper/Buildsystem/*.pm with man/dh_auto_pod script.
* man/dh_auto_pod $step - generates full dh_auto_$step POD (replaces
  placeholders).
* man/dh_auto_pod - generates full dh_auto.pod (replaces placeholders).

Signed-off-by: Modestas Vainius <modestas@vainius.eu>

1 files changed, 129 insertions, 0 deletions

diff --git a/Debian/Debhelper/Buildsystem/python_distutils.pm b/Debian/Debhelper/Buildsystem/python_distutils.pm
index ad4ea87..8266fa0 100644
--- a/Debian/Debhelper/Buildsystem/python_distutils.pm
+++ b/Debian/Debhelper/Buildsystem/python_distutils.pm
@@ -7,6 +7,37 @@
 
 package Debian::Debhelper::Buildsystem::python_distutils;
 
+=head1 NAME
+
+B<python_distutils> - Python Distutils (setup.py)
+
+=head1 SYNOPSIS
+
+B<dh_auto_*> [B<--buildsystem>=I<python_distutils>] ...
+
+=head1 DESCRIPTION
+
+Python Distribution Utilities (Distutils for short) is a standard Python build
+system. It is used to package most of the Python modules in the source
+distribution form. Typically, only two steps (build and install) are needed to
+finish installation of the Distutils based Python module. This build system can
+be typically identified by presence of the F<setup.py> in the source directory.
+
+=head1 DH_AUTO NOTES
+
+Out of source tree building is done by default but in source building is also
+supported. PLEASE NOTE that B<default build directory> is B<$srcdir/build>
+where $srcdir is a path to the source directory.
+
+Due to design flaws of Distutils, it is not possible to set a B<custom> build
+directory via command line arguments to F<setup.py>. Therefore, the same effect
+is achieved by writing appropriate F<.pydistutils.cfg> file to the build
+directory and pointing $HOME environment variable to the build directory.
+
+=head1 BUILD PROCESS
+
+=cut
+
 use strict;
 use Cwd ();
 use Debian::Debhelper::Dh_Lib qw(error);
@@ -81,17 +112,104 @@ sub setup_py {
 	$this->doit_in_sourcedir("python", "setup.py", $act, @_);
 }
 
+=head2 Configure step
+
+=over 4
+
+=item I<Behaviour>
+
+Do nothing but stop auto-selection process.
+
+=item I<Auto-selection>
+
+If neither F<configure>, F<Makefile.PL> exist, but F<setup.py> exists in the
+source directory.
+
+=back
+
+=cut
+
+=head2 Build step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute C<python setup.py build>.
+
+=item I<Auto-selection>
+
+If F<Makefile>, F<makefile> F<GNUmakefile> do not exist in the build directory
+and F<setup.py> file exists in the source directory.
+
+=back
+
+=cut
 sub build {
 	my $this=shift;
 	$this->setup_py("build", @_);
 }
 
+=head2 Test step
+
+=over 4
+
+=item I<Behaviour>
+
+Do nothing but stop auto-selection process.
+
+=item I<Auto-selection>
+
+F<Makefile>, F<makefile>, F<GNUmakefile> do not exist in the build directory and
+F<setup.py> file exists in the source directory.
+
+=back
+
+=cut
+
+=head2 Install step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute C<python setup.py install> passing temporary installation directory via
+C<--root> parameter. C<--no-compile> and C<-O0> parameters are also passed by
+default. See L<dh_auto_install(1)> for more information.
+
+=item I<Auto-selection>
+
+F<Makefile>, F<makefile>, F<GNUmakefile> do not exist in the build directory and
+F<setup.py> file exists in the source directory.
+
+=back
+
+=cut
 sub install {
 	my $this=shift;
 	my $destdir=shift;
 	$this->setup_py("install", "--root=$destdir", "--no-compile", "-O0", @_);
 }
 
+=head2 Clean step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute C<python setup.py clean -a>. Additional parameters (if specified) are
+passed to the latter command. F<.pydistutils.cfg> is also removed if it was
+created (together with the build directory if it is ends up empty). Finally,
+recursively find and delete all *.pyc files from the source directory.
+
+=item I<Auto-selection>
+
+F<Makefile>, F<makefile>, F<GNUmakefile> do not exist in the build directory and
+F<setup.py> file exists in the source directory.
+
+=back
+
+=cut
 sub clean {
 	my $this=shift;
 	$this->setup_py("clean", "-a", @_);
@@ -106,4 +224,15 @@ sub clean {
 	$this->doit_in_sourcedir('find', '.', '-name', '*.pyc', '-exec', 'rm', '{}', ';');
 }
 
+=head1 SEE ALSO
+
+L<dh_auto(7)>
+
+=head1 AUTHORS
+
+ Joey Hess <joeyh@debian.org>
+ Modestas Vainius <modestas@vainius.eu>
+
+=cut
+
 1;