from setuptools import setup
-A plugin for setuptools to find files under Mercurial version control to be
-automatically included as package data.
-It works correctly with Mercurial 1.x and uses Mercurial's Python library by
-default. It will however fall back to use the command line programm hg(1) to
-determin the list of files.
+setuptools_hg is a plugin for setuptools that enables setuptools to find files
+under the Mercurial version control system.
+It uses the Mercurial Python library by default and falls back to use the
+command line programm ``hg(1)``. That's especially useful inside virtualenvs
+that don't have access to the system wide installed Mercurial lib (e.g. when
+created with ``--no-site-packages``).
+.. note:: The setuptools feature
+ You can read about the hooks used by setuptool_hg in the
+ `setuptools documentation`_. It basically returns a list of files that are
+ under Mercurial version control when running the ``setup`` function, e.g. if
+ you create a source and binary distribution. It's a simple yet effective way
+ of not having to define package data (non-Python files) manually in MANIFEST
+ templates (``MANIFEST.in``).
+.. _setuptools documentation: http://peak.telecommunity.com/DevCenter/setuptools#adding-support-for-other-revision-control-systems
+Here's an example of a setup.py that uses setuptools_hg::
+ from setuptools import setup, find_packages
+If you run this setup.py setuptools will automatically download setuptools_hg
+to the directory where the setup.py is located at (and won't install it
+anywhere else) to get all package data files from the Mercurial repository.
+Set the ``HG_SETUPTOOLS_FORCE_CMD`` environment variable before running
+setup.py if you want to enforce the use of the hg command.
"Intended Audience :: Developers",
"Operating System :: OS Independent",
"License :: OSI Approved :: GNU General Public License (GPL)",
- "Topic :: Software Development :: Version Control"
+ "Topic :: Software Development :: Version Control",
+ "Framework :: Setuptools Plugin",