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>

6 files changed, 758 insertions, 0 deletions

diff --git a/Debian/Debhelper/Buildsystem/autoconf.pm b/Debian/Debhelper/Buildsystem/autoconf.pm
index 60fa9e85..9121a1d7 100644
--- a/Debian/Debhelper/Buildsystem/autoconf.pm
+++ b/Debian/Debhelper/Buildsystem/autoconf.pm
@@ -6,6 +6,34 @@
 
 package Debian::Debhelper::Buildsystem::autoconf;
 
+=head1 NAME
+
+B<autoconf> - GNU Autoconf (configure)
+
+=head1 SYNOPSIS
+
+B<dh_auto_*> [B<--buildsystem>=I<autoconf>] ...
+
+=head1 DESCRIPTION
+
+GNU Autoconf is a popular cross-platform build system. Autoconf F<configure>
+script prepares the source for building and generates necessary F<Makefile>s
+and other temporary files in the build directory. Then a standard set of
+make targets needs to be executed in the build directory to complete source
+build process. GNU Autoconf build system can be typically identified by
+presence of the F<configure> script in the source directory.
+
+=head1 DH_AUTO NOTES
+
+Both in source (default) and out of source tree building modes are supported.
+However, please note that some original source packages might not be compatible
+with out of source tree building mode of Autoconf and hence build process may
+fail later even if the I<configure> step succeeds. 
+
+=head1 BUILD PROCESS
+
+=cut
+
 use strict;
 use Debian::Debhelper::Dh_Lib qw(dpkg_architecture_value sourcepackage);
 use base 'Debian::Debhelper::Buildsystem::makefile';
@@ -25,6 +53,35 @@ sub check_auto_buildable {
 	return 0;
 }
 
+=head2 Configure step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute F<configure> from the source directory with working directory set to
+the build directory. A set of standard arguments are passed to the F<configure>
+script:
+
+ --build=`dpkg_architecture -qDEB_BUILD_GNU_TYPE`
+ --prefix=/usr
+ --includedir=${prefix}/include
+ --mandir=${prefix}/share/man
+ --infodir=${prefix}/share/info
+ --sysconfdir=/etc
+ --localstatedir=/var
+ --libexecdir=${prefix}/lib/$name_of_debian_source_package
+ --disable-maintainer-mode
+ --disable-dependency-tracking
+ --host=`dpkg_architecture -qDEB_HOST_GNU_TYPE` (if different from --build)
+
+=item I<Auto-selection>
+
+If executable file F<configure> exists in the source directory.
+
+=back
+
+=cut
 sub configure {
 	my $this=shift;
 
@@ -52,4 +109,79 @@ sub configure {
 	$this->doit_in_builddir($this->get_source_rel2builddir("configure"), @opts, @_);
 }
 
+=head2 Build step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute C<make> in the build directory. See I<makefile> build system
+documentation for more information.
+
+=item I<Auto-selection>
+
+It is normal for the I<makefile> build system to be auto-selected at this step.
+
+=back
+
+=head2 Test step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute either C<make test> or C<make check> in the build directory. See
+I<makefile> build system documentation for more information.
+
+=item I<Auto-selection>
+
+It is normal for the I<makefile> build system to be auto-selected at this step.
+
+=back
+
+=head2 Install step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute C<make install DESTDIR=$destdir> in the build directory with $destdir
+set to the appropriate temporary installation directory. See I<makefile> build
+system documentation for more information.
+
+=item I<Auto-selection>
+
+It is normal for the I<makefile> build system to be auto-selected at this step.
+
+=back
+
+=head2 Clean step
+
+=over 4
+
+=item I<Behaviour>
+
+Remove the build directory if building out of source tree or execute C<make
+distclean> if building in source. See I<makefile> build system documentation
+for more information.
+
+=item I<Auto-selection>
+
+It is normal for the I<makefile> build system to be auto-selected at this step.
+
+=back
+
+=head1 SEE ALSO
+
+L<dh_auto_makefile(7)>
+
+L<dh_auto(7)>
+
+=head1 AUTHORS
+
+ Joey Hess <joeyh@debian.org>
+ Modestas Vainius <modestas@vainius.eu>
+
+=cut
+
 1;
diff --git a/Debian/Debhelper/Buildsystem/cmake.pm b/Debian/Debhelper/Buildsystem/cmake.pm
index 56628740..0275bfb8 100644
--- a/Debian/Debhelper/Buildsystem/cmake.pm
+++ b/Debian/Debhelper/Buildsystem/cmake.pm
@@ -6,6 +6,36 @@
 
 package Debian::Debhelper::Buildsystem::cmake;
 
+=head1 NAME
+
+B<cmake> - CMake (CMakeLists.txt)
+
+=head1 SYNOPSIS
+
+B<dh_auto_*> [B<--buildsystem>=I<cmake>] ...
+
+=head1 DESCRIPTION
+
+CMake is a family of tools designed to build, test and package software. CMake
+generates F<Makefile>s and other temporary files in the build directory from
+the directives present in the F<CMakeLists.txt> and a couple of other build
+system source files. Then a standard set of make targets needs to be executed
+in the build directory to complete source building process. CMake is available
+in the cmake package that is essential throughout the whole build process.
+
+=head1 DH_AUTO NOTES
+
+Out of source tree building is done by default if this debhelper build system
+is selected. This is due to the fact that there is no way to properly clean up
+build directory from temporary files unless it is removed completely.
+Therefore I<clean> step cannot be fully implemented if building is done in
+source. However, the user may still enable in source building by explicitly
+specifying a build directory path that is equal to the source directory path.
+
+=head1 BUILD PROCESS
+
+=cut
+
 use strict;
 use base 'Debian::Debhelper::Buildsystem::makefile';
 
@@ -29,6 +59,27 @@ sub new {
 	return $this;
 }
 
+=head2 Configure step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute C<cmake> in the build directory passing a path to the source directory
+and defining the following flags:
+
+ -DCMAKE_INSTALL_PREFIX=/usr
+ -DCMAKE_SKIP_RPATH=ON
+ -DCMAKE_VERBOSE_MAKEFILE=ON
+
+=item I<Auto-selection>
+
+If F<CMakeLists.txt> file exists but neither F<configure>, F<Makefile.PL>,
+F<setup.py> or F<Build.PL> exist in the source directory.
+
+=back
+
+=cut
 sub configure {
 	my $this=shift;
 	my @flags;
@@ -42,4 +93,78 @@ sub configure {
 	$this->doit_in_builddir("cmake", $this->get_source_rel2builddir(), @flags);
 }
 
+=head2 Build step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute C<make> in the build directory. See I<makefile> build system documentation
+for more information.
+
+=item I<Auto-selection>
+
+It is normal for the I<makefile> build system to be auto-selected at this step.
+
+=back
+
+=head2 Test step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute C<make test> in the build directory. See I<makefile> build system
+documentation for more information.
+
+=item I<Auto-selection>
+
+It is normal for the I<makefile> build system to be auto-selected at this step.
+
+=back
+
+=head2 Install step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute C<make install DESTDIR=$destdir> in the build directory with $destdir
+set to the appropriate temporary installation directory. See I<makefile> build
+system documentation for more information.
+
+=item I<Auto-selection>
+
+It is normal for the I<makefile> build system to be auto-selected at this step.
+
+=back
+
+=head2 Clean step
+
+=over 4
+
+=item I<Behaviour>
+
+Remove the build directory if building out of source tree (complete clean up)
+or execute C<make clean> if building in source (incomplete clean up). See
+I<makefile> build system documentation for more information.
+
+=item I<Auto-selection>
+
+It is normal for the I<makefile> build system to be auto-selected at this step.
+
+=back
+
+=head1 SEE ALSO
+
+L<dh_auto_makefile(7)>
+
+L<dh_auto(7)>
+
+=head1 AUTHORS
+
+ Modestas Vainius <modestas@vainius.eu>
+
+=cut
+
 1;
diff --git a/Debian/Debhelper/Buildsystem/makefile.pm b/Debian/Debhelper/Buildsystem/makefile.pm
index d84d3349..32ad5178 100644
--- a/Debian/Debhelper/Buildsystem/makefile.pm
+++ b/Debian/Debhelper/Buildsystem/makefile.pm
@@ -6,6 +6,56 @@
 
 package Debian::Debhelper::Buildsystem::makefile;
 
+=head1 NAME
+
+B<makefile> - make (Makefile)
+
+=head1 SYNOPSIS
+
+B<dh_auto_*> [B<--buildsystem>=I<makefile>] ...
+
+=head1 DESCRIPTION
+
+Makefile based projects use C<make> to control build process. C<make> utility
+is the most popular tool on *NIX for building & installing packages from
+source. It is also a basis for most other popular build systems. For example,
+GNU Autoconf (autoconf) or CMake (cmake) generate F<Makefile>s during I<configure>
+step and leave the rest of build process for C<make> to handle.
+
+=head1 DH_AUTO NOTES
+
+Since C<make> itself does not strictly define standard target names, a couple
+of the most popular targets are tried for each building step. Whichever first
+of them is discovered to exist, it is run. If neither of the tried targets
+exist in the actual, the building step is assumed to have completed
+successfully. However, if executed C<make> target fails, the respective dh_auto
+program will fail too.
+
+If MAKE environment variable is set, its value is executed rather than default
+C<make> command.
+
+Both in source (default) and out of source tree building modes are supported.
+Either F<Makefile>, F<makefile> or F<GNUmakefile> file should be present in the
+build directory for this debhelper build system to work.
+
+=head1 BUILD PROCESS
+
+=head2 Configure step
+
+=over 4
+
+=item I<Behaviour>
+
+Do nothing (auto-selection continues).
+
+=item I<Auto-selection>
+
+It will never be auto-selected at this step.
+
+=back
+
+=cut
+
 use strict;
 use Debian::Debhelper::Dh_Lib qw(escape_shell);
 use base 'Debian::Debhelper::Buildsystem';
@@ -69,22 +119,92 @@ sub check_auto_buildable {
 	return 0;
 }
 
+=head2 Build step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute C<make> (without arguments) with working directory changed to the build
+directory.
+
+=item I<Auto-selection>
+
+If either F<Makefile>, F<makefile> or F<GNUmakefile> exists in the build
+directory, but F<Makefile.PL> does not exist in the source directory.
+
+=back
+
+=cut
 sub build {
 	my $this=shift;
 	$this->doit_in_builddir($this->{makecmd}, @_);
 }
 
+=head2 Test step
+
+=over 4
+
+=item I<Behaviour>
+
+Try to C<make> either I<test> or I<check> target (the first existing one) with
+working directory changed to the build directory.
+
+=item I<Auto-selection>
+
+If either F<Makefile>, F<makefile> or F<GNUmakefile> exists in the build
+directory, but F<Makefile.PL> does not exist in the source directory.
+
+=back
+
+=cut
 sub test {
 	my $this=shift;
 	$this->make_first_existing_target(['test', 'check'], @_);
 }
 
+=head2 Install step
+
+=over 4
+
+=item I<Behaviour>
+
+Try to run C<make install DESTDIR=$destdir> with working directory changed to
+the build directory. $desdir is the path to the appropriate temporary
+installation directory under debian/ (see L<dh_auto_install(1)>).
+
+=item I<Auto-selection>
+
+If either F<Makefile>, F<makefile> or F<GNUmakefile> exists in the build
+directory, but F<Makefile.PL> does not exist in the source directory.
+
+=back
+
+=cut
 sub install {
 	my $this=shift;
 	my $destdir=shift;
 	$this->make_first_existing_target(['install'], "DESTDIR=$destdir", @_);
 }
 
+=head2 Clean step
+
+=over 4
+
+=item I<Behaviour>
+
+When building in source, try to C<make> either I<distclean>, I<realclean> or
+I<clean> target (the first existing one) in the source directory. When building
+out of source tree, recursively remove the whole build directory.
+
+=item I<Auto-selection>
+
+If either F<Makefile>, F<makefile> or F<GNUmakefile> exists in the build
+directory, but F<Makefile.PL> does not exist in the source directory.
+
+=back
+
+=cut
 sub clean {
 	my $this=shift;
 	if (!$this->rmdir_builddir()) {
@@ -92,4 +212,15 @@ sub clean {
 	}
 }
 
+=head1 SEE ALSO
+
+L<dh_auto(7)>
+
+=head1 AUTHORS
+
+ Joey Hess <joeyh@debian.org>
+ Modestas Vainius <modestas@vainius.eu>
+
+=cut
+
 1;
diff --git a/Debian/Debhelper/Buildsystem/perl_build.pm b/Debian/Debhelper/Buildsystem/perl_build.pm
index 3567cb1a..26210152 100644
--- a/Debian/Debhelper/Buildsystem/perl_build.pm
+++ b/Debian/Debhelper/Buildsystem/perl_build.pm
@@ -6,6 +6,32 @@
 
 package Debian::Debhelper::Buildsystem::perl_build;
 
+=head1 NAME
+
+B<perl_build> - Perl Module::Build (Build.PL)
+
+=head1 SYNOPSIS
+
+B<dh_auto_*> [B<--buildsystem>=I<perl_build>] ...
+
+=head1 DESCRIPTION
+
+Module::Build is a system for building, testing, and installing Perl modules.
+It does not require a C<make> on your system - most of the Module::Build code is
+pure-perl and written in a very cross-platform way. Its only prerequisites are
+modules that are included with perl 5.6.0. Typically, Module::Build build system
+can be identified by presence of the F<Build.PL> script in the source
+directory.
+
+=head1 DH_AUTO NOTES
+
+Out of source tree building is not supported. C<MODULEBUILDRC=/dev/null>
+environment variable is exported in each building step.
+
+=head1 BUILD PROCESS
+
+=cut
+
 use strict;
 use base 'Debian::Debhelper::Buildsystem';
 
@@ -37,31 +63,128 @@ sub new {
 	return $this;
 }
 
+=head2 Configure step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute C<perl Build.PL> passing C<installdirs=vendor> parameter by default.
+Environment variable C<PERL_MM_USE_DEFAULT> is set before running the script.
+
+=item I<Auto-selection>
+
+If F<configure>, F<Makefile.PL>, F<setup.py> do not exist, but F<Build.PL>
+exists in the source directory.
+
+=back
+
+=cut
 sub configure {
 	my $this=shift;
 	$ENV{PERL_MM_USE_DEFAULT}=1;
 	$this->do_perl("Build.PL", "installdirs=vendor", @_);
 }
 
+=head2 Build step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute C<perl Build>.
+
+=item I<Auto-selection>
+
+If F<Makefile>, F<makefile>, F<GNUmakefile> (build directory) and F<setup.py>
+(source directory) do not exist, but F<Build.PL> and F<Build> files exist in
+the source directory.
+
+=back
+
+=cut
 sub build {
 	my $this=shift;
 	$this->do_perl("Build", @_);
 }
 
+=head2 Test step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute C<perl Build test>.
+
+=item I<Auto-selection>
+
+If F<Makefile>, F<makefile>, F<GNUmakefile> (build directory) and F<setup.py>
+(source directory) do not exist, but F<Build.PL> and F<Build> files exist in
+the source directory.
+
+=back
+
+=cut
 sub test {
 	my $this=shift;
 	$this->do_perl("Build", "test", @_);
 }
 
+=head2 Install step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute C<perl Build install destdir=$destdir create_packlist=0>. $destdir is
+the path to the temporary installation directory (see L<dh_auto_install(1)>).
+
+=item I<Auto-selection>
+
+If F<Makefile>, F<makefile>, F<GNUmakefile> (build directory) and F<setup.py>
+(source directory) do not exist, but F<Build.PL> and F<Build> files exist in
+the source directory.
+
+=back
+
+=cut
 sub install {
 	my $this=shift;
 	my $destdir=shift;
 	$this->do_perl("Build", "install", "destdir=$destdir", "create_packlist=0", @_);
 }
 
+=head2 Clean step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute C<perl Build --allow_mb_mismatch 1 distclean>.
+
+=item I<Auto-selection>
+
+If F<Makefile>, F<makefile>, F<GNUmakefile> (build directory) and F<setup.py>
+(source directory) do not exist, but F<Build.PL> and F<Build> files exist in
+the source directory.
+
+=back
+
+=cut
 sub clean {
 	my $this=shift;
 	$this->do_perl("Build", "--allow_mb_mismatch", 1, "distclean", @_);
 }
 
+=head1 SEE ALSO
+
+L<dh_auto(7)>
+
+=head1 AUTHORS
+
+ Joey Hess <joeyh@debian.org>
+ Modestas Vainius <modestas@vainius.eu>
+
+=cut
+
 1;
diff --git a/Debian/Debhelper/Buildsystem/perl_makemaker.pm b/Debian/Debhelper/Buildsystem/perl_makemaker.pm
index 07a827ac..102e23f5 100644
--- a/Debian/Debhelper/Buildsystem/perl_makemaker.pm
+++ b/Debian/Debhelper/Buildsystem/perl_makemaker.pm
@@ -6,6 +6,29 @@
 
 package Debian::Debhelper::Buildsystem::perl_makemaker;
 
+=head1 NAME
+
+B<perl_makemaker> - Perl ExtUtils::MakeMaker (Makefile.PL)
+
+=head1 SYNOPSIS
+
+B<dh_auto_*> [B<--buildsystem>=I<perl_makemaker>] ...
+
+=head1 DESCRIPTION
+
+Perl ExtUtils::MakeMaker utility is designed to write a Makefile for an
+extension module from a Makefile.PL (at configure step). The rest of build
+process is handled by C<make>. Typically, ExtUtils::MakeMaker build system can
+be identified by presence of the F<Makefile.PL> script in the source directory.
+
+=head1 DH_AUTO NOTES
+
+Out of source tree building is not supported.
+
+=head1 BUILD PROCESS
+
+=cut
+
 use strict;
 use base 'Debian::Debhelper::Buildsystem::makefile';
 
@@ -42,6 +65,24 @@ sub new {
 	return $this;
 }
 
+=head2 Configure step
+
+=over
+
+=item I<Behaviour>
+
+Execute C<Makefile.PL> script passing C<INSTALLDIRS=vendor> and
+C<create_packlist=0> parameters. Environment variables C<PERL_MM_USE_DEFAULT=1>
+and C<PERL_AUTOINSTALL=--skipdeps> are exported before running the script.
+
+=item I<Auto-selection>
+
+If F<Makefile.PL> file exists but F<configure> does not exist in the source
+directory.
+
+=back
+
+=cut
 sub configure {
 	my $this=shift;
 	# If set to a true value then MakeMaker's prompt function will
@@ -55,10 +96,87 @@ sub configure {
 	    @_);
 }
 
+=head2 Build step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute C<make> in the build directory. See I<makefile> build system
+documentation for more information.
+
+=item I<Auto-selection>
+
+Both F<Makefile.PL> and F<Makefile> exist in the source directory.
+
+=back
+
+=head2 Test step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute C<make test> in the source directory. See I<makefile> build system
+documentation for more information.
+
+=item I<Auto-selection>
+
+Both F<Makefile.PL> and F<Makefile> exist in the source directory.
+
+=back
+
+=cut
+
+=head2 Install step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute C<make install DESTDIR=$destdir PREFIX=/usr> in the source directory
+with $destdir set to the appropriate temporary installation directory. See
+I<makefile> build system documentation for more information.
+
+=item I<Auto-selection>
+
+Both F<Makefile.PL> and F<Makefile> exist in the source directory.
+
+=back
+
+=cut
 sub install {
 	my $this=shift;
 	my $destdir=shift;
 	$this->SUPER::install($destdir, "PREFIX=/usr", @_);
 }
 
+=head2 Clean step
+
+=over 4
+
+=item I<Behaviour>
+
+Execute C<make distclean> in the source directory. See I<makefile> build system
+documentation for more information.
+
+=item I<Auto-selection>
+
+Both F<Makefile.PL> and F<Makefile> exist in the source directory.
+
+=back
+
+=head1 SEE ALSO
+
+L<dh_auto_makefile(7)>
+
+L<dh_auto(7)>
+
+=head1 AUTHORS
+
+ Joey Hess <joeyh@debian.org>
+ Modestas Vainius <modestas@vainius.eu>
+
+=cut
+
 1;
diff --git a/Debian/Debhelper/Buildsystem/python_distutils.pm b/Debian/Debhelper/Buildsystem/python_distutils.pm
index ad4ea877..8266fa0b 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;