Improve documentation of packaging hooks

Doc/packaging/commandhooks.rst

@@ -1,36 +1,47 @@
 .. TODO integrate this in commandref and configfile
 
+.. _packaging-command-hooks:
+
 =============
 Command hooks
 =============
 
 Packaging provides a way of extending its commands by the use of pre- and
-post- command hooks. The hooks are simple Python functions (or any callable
+post-command hooks.  Hooks are Python functions (or any callable object) that
-objects) and are specified in the config file using their full qualified names.
+take a command object as argument.  They're specified in :ref:`config files
-The pre-hooks are run after the command is finalized (its options are
+<packaging-config-filenames>` using their fully qualified names.  After a
-processed), but before it is run. The post-hooks are run after the command
+command is finalized (its options are processed), the pre-command hooks are
-itself. Both types of hooks receive an instance of the command object.
+executed, then the command itself is run, and finally the post-command hooks are
+executed.
 
 See also global setup hooks in :ref:`setupcfg-spec`.
 
 
-Sample usage of hooks
+.. _packaging-finding-hooks:
-=====================
 
-Firstly, you need to make sure your hook is present in the path. This is usually
+Finding hooks
-done by dropping them to the same folder where `setup.py` file lives ::
+=============
 
-  # file: myhooks.py
+As a hook is configured with a Python dotted name, it must either be defined in
-  def my_install_hook(install_cmd):
+a module installed on the system, or in a module present in the project
-      print "Oh la la! Someone is installing my project!"
+directory, where the :file:`setup.cfg` file lives::
 
-Then, you need to point to it in your `setup.cfg` file, under the appropriate
+  # file: _setuphooks.py
-command section ::
+
+  def hook(install_cmd):
+      metadata = install_cmd.dist.metadata
+      print('Hooked while installing %r %s!' % (metadata['Name'],
+                                                metadata['Version']))
+
+Then you need to configure it in :file:`setup.cfg`::
 
   [install_dist]
-  pre-hook.project = myhooks.my_install_hook
+  pre-hook.a = _setuphooks.hook
 
-The hooks defined in different config files (system-wide, user-wide and
+Packaging will add the project directory to :data:`sys.path` and find the
-package-wide) do not override each other as long as they are specified with
+``_setuphooks`` module.
-different aliases (additional names after the dot). The alias in the example
+
-above is ``project``.
+Hooks defined in different config files (system-wide, user-wide and
+project-wide) do not override each other as long as they are specified with
+different aliases (additional names after the dot).  The alias in the example
+above is ``a``.

Doc/packaging/setupcfg.rst

@@ -178,17 +178,20 @@ compilers
 
 setup_hooks
    Defines a list of callables to be called right after the :file:`setup.cfg`
-   file is read, before any other processing.  The callables are executed in the
+   file is read, before any other processing.  Each value is a Python dotted
+   name to an object, which has to be defined in a module present in the project
+   directory alonside :file:`setup.cfg` or on Python's :data:`sys.path` (see
+   :ref:`packaging-finding-hooks`).  The callables are executed in the
    order they're found in the file; if one of them cannot be found, tools should
    not stop, but for example produce a warning and continue with the next line.
    Each callable receives the configuration as a dictionary (keys are
    :file:`setup.cfg` sections, values are dictionaries of fields) and can make
-   any changes to it.  *optional*, *multi*
+   any change to it.  *optional*, *multi*
 
    Example::
 
       [global]
-      setup_hooks = package.setup.customize_dist
+      setup_hooks = _setuphooks.customize_config
 
 
 Metadata