Merged revisions 71473 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r71473 | tarek.ziade | 2009-04-11 16:55:07 +0200 (Sat, 11 Apr 2009) | 1 line

  #5732: added the check command into Distutils
........

2 files changed, 65 insertions, 0 deletions

diff --git a/Doc/distutils/apiref.rst b/Doc/distutils/apiref.rst
index ce260d9..490e7f3 100644
--- a/Doc/distutils/apiref.rst
+++ b/Doc/distutils/apiref.rst
@@ -1950,6 +1950,19 @@ This is described in more detail in :pep:`301`.
 
 .. % todo
 
+:mod:`distutils.command.check` --- Check the meta-data of a package
+===================================================================
+
+.. module:: distutils.command.check
+   :synopsis: Check the metadata of a package
+
+
+The ``check`` command performs some tests on the meta-data of a package.
+It makes sure for example that all required meta-data are provided through
+the arguments passed to the :func:`setup` function.
+
+.. % todo
+
 
 Creating a new Distutils command
 ================================
diff --git a/Doc/distutils/examples.rst b/Doc/distutils/examples.rst
index b495928..d5918a5 100644
--- a/Doc/distutils/examples.rst
+++ b/Doc/distutils/examples.rst
@@ -233,6 +233,58 @@ With exactly the same source tree layout, this extension can be put in the
          ext_modules=[Extension('foopkg.foo', ['foo.c'])],
          )
 
+Checking a package
+==================
+
+The ``check`` command allows you to verify if your package meta-data are
+meeting the minimum requirements to build a distribution.
+
+To run it, just call it over your :file:`setup.py` script. If something is
+missing, ``check`` will display a warning.
+
+Let's take an example with a simple script::
+
+    from distutils.core import setup
+
+    setup(name='foobar')
+
+Running the ``check`` command will display some warnings::
+
+    $ python setup.py check
+    running check
+    warning: check: missing required meta-data: version ,url
+    warning: check: missing meta-data: either (author and author_email) or
+             (maintainer and maintainer_email) must be supplied
+
+
+If you use the reStructuredText syntax in the `long_description` field and
+`docutils <http://docutils.sourceforge.net/>`_ is installed you can check if
+the syntax is fine with the ``check`` command, using the `restructuredtext`
+option.
+
+For example, if the :file:`setup.py` script is changed like this::
+
+    from distutils.core import setup
+
+    desc = """\
+    My description
+    =============
+
+    This is the description of the ``foobar`` package.
+    """
+
+    setup(name='foobar', version='1', author='tarek',
+        author_email='tarek@ziade.org',
+        url='http://example.com', long_description=desc)
+
+Where the long description is broken, ``check`` will be able to detect it
+by using the `docutils` parser::
+
+    $ pythontrunk setup.py check --restructuredtext
+    running check
+    warning: check: Title underline too short. (line 2)
+    warning: check: Could not finish the parsing.
+
 .. % \section{Multiple extension modules}
 .. % \label{multiple-ext}