Merge packaging doc fix

9 files changed, 103 insertions, 31 deletions

diff --git a/Doc/distutils/index.rst b/Doc/distutils/index.rst
index 5fa25a6..b3a5231 100644
--- a/Doc/distutils/index.rst
+++ b/Doc/distutils/index.rst
@@ -14,6 +14,10 @@ the module developer's point of view, describing how to use the Distutils to
 make Python modules and extensions easily available to a wider audience with
 very little overhead for build/release/install mechanics.
 
+.. deprecated:: 3.3
+   :mod:`packaging` replaces Distutils.  See :ref:`packaging-index` and
+   :ref:`packaging-install-index`.
+
 .. toctree::
    :maxdepth: 2
    :numbered:
@@ -36,9 +40,3 @@ following the above guidelines:
 .. toctree::
 
    install.rst
-
-
-.. seealso::
-
-   :ref:`packaging-index` and :ref:`packaging-install-index`
-      Documentation of Packaging, the new version of Distutils.
diff --git a/Doc/install/index.rst b/Doc/install/index.rst
new file mode 100644
index 0000000..bb2e9c5
--- /dev/null
+++ b/Doc/install/index.rst
@@ -0,0 +1,56 @@
+.. _packaging-install-index:
+
+******************************
+  Installing Python Projects
+******************************
+
+:Author: The Fellowship of the Packaging
+:Release: |version|
+:Date: |today|
+
+.. TODO: Fill in XXX comments
+
+.. The audience for this document includes people who don't know anything
+   about Python and aren't about to learn the language just in order to
+   install and maintain it for their users, i.e. system administrators.
+   Thus, I have to be sure to explain the basics at some point:
+   sys.path and PYTHONPATH at least. Should probably give pointers to
+   other docs on "import site", PYTHONSTARTUP, PYTHONHOME, etc.
+
+   Finally, it might be useful to include all the material from my "Care
+   and Feeding of a Python Installation" talk in here somewhere. Yow!
+
+.. topic:: Abstract
+
+   This document describes Packaging from the end-user's point of view: it
+   explains how to extend the functionality of a standard Python installation by
+   building and installing third-party Python modules and applications.
+
+
+This guide is split into a simple overview  followed by a longer presentation of
+the :program:`pysetup` script, the Python package management tool used to
+build, distribute, search for, install, remove and list Python distributions.
+
+.. TODO integrate install and pysetup instead of duplicating
+
+.. toctree::
+   :maxdepth: 2
+   :numbered:
+
+   install
+   pysetup
+   pysetup-config
+   pysetup-servers
+
+
+.. seealso::
+
+   :ref:`packaging-index`
+      The manual for developers of Python projects who want to package and
+      distribute them. This describes how to use :mod:`packaging` to make
+      projects easily found and added to an existing Python installation.
+
+   :mod:`packaging`
+      A library reference for developers of packaging tools wanting to use
+      standalone building blocks like :mod:`~packaging.version` or
+      :mod:`~packaging.metadata`, or extend Packaging itself.
diff --git a/Doc/library/distutils.rst b/Doc/library/distutils.rst
index f1a0f6b..53a69ae 100644
--- a/Doc/library/distutils.rst
+++ b/Doc/library/distutils.rst
@@ -12,21 +12,24 @@ additional modules into a Python installation.  The new modules may be either
 100%-pure Python, or may be extension modules written in C, or may be
 collections of Python packages which include modules coded in both Python and C.
 
-This package is discussed in two separate chapters:
+.. deprecated:: 3.3
+   :mod:`packaging` replaces Distutils.  See :ref:`packaging-index` and
+   :ref:`packaging-install-index`.
 
 
+User documentation and API reference are provided in another document:
+
 .. seealso::
 
    :ref:`distutils-index`
       The manual for developers and packagers of Python modules.  This describes
       how to prepare :mod:`distutils`\ -based packages so that they may be
-      easily installed into an existing Python installation.
+      easily installed into an existing Python installation.  If also contains
+      instructions for end-users wanting to install a distutils-based package,
+      :ref:`install-index`.
 
-   :ref:`install-index`
-      An "administrators" manual which includes information on installing
-      modules into an existing Python installation.  You do not need to be a
-      Python programmer to read this manual.
 
+.. trick to silence a Sphinx warning
 
 .. toctree::
    :hidden:
diff --git a/Doc/packaging/index.rst b/Doc/packaging/index.rst
index 0e80818..d3d0dec 100644
--- a/Doc/packaging/index.rst
+++ b/Doc/packaging/index.rst
@@ -4,7 +4,7 @@
  Distributing Python Projects
 ##############################
 
-:Authors: The Fellowship of The Packaging
+:Authors: The Fellowship of the Packaging
 :Email: distutils-sig@python.org
 :Release: |version|
 :Date: |today|
diff --git a/Doc/tools/sphinxext/indexcontent.html b/Doc/tools/sphinxext/indexcontent.html
index 10f9d26..778346f 100644
--- a/Doc/tools/sphinxext/indexcontent.html
+++ b/Doc/tools/sphinxext/indexcontent.html
@@ -21,9 +21,9 @@
       <p class="biglink"><a class="biglink" href="{{ pathto("c-api/index") }}">Python/C API</a><br/>
          <span class="linkdescr">reference for C/C++ programmers</span></p>
       <p class="biglink"><a class="biglink" href="{{ pathto("install/index") }}">Installing Python Projects</a><br/>
-         <span class="linkdescr">information for installers &amp; sys-admins</span></p>
+         <span class="linkdescr">finding and installing modules and applications</span></p>
       <p class="biglink"><a class="biglink" href="{{ pathto("packaging/index") }}">Distributing Python Projects</a><br/>
-         <span class="linkdescr">sharing modules with others</span></p>
+         <span class="linkdescr">packaging and distributing modules and applications</span></p>
       <p class="biglink"><a class="biglink" href="{{ pathto("documenting/index") }}">Documenting Python</a><br/>
          <span class="linkdescr">guide for documentation authors</span></p>
       <p class="biglink"><a class="biglink" href="{{ pathto("faq/index") }}">FAQs</a><br/>
diff --git a/Lib/packaging/command/check.py b/Lib/packaging/command/check.py
index 94c4a97..6715db9 100644
--- a/Lib/packaging/command/check.py
+++ b/Lib/packaging/command/check.py
@@ -32,7 +32,7 @@ class check(Command):
         # XXX we could use a special handler for this, but would need to test
         # if it works even if the logger has a too high level
         self._warnings.append((msg, args))
-        return logger.warning(self.get_command_name() + msg, *args)
+        return logger.warning('%s: %s' % (self.get_command_name(), msg), *args)
 
     def run(self):
         """Runs the command."""
diff --git a/Lib/packaging/tests/support.py b/Lib/packaging/tests/support.py
index 66b5583..ae65a1d 100644
--- a/Lib/packaging/tests/support.py
+++ b/Lib/packaging/tests/support.py
@@ -90,17 +90,23 @@ class LoggingCatcher:
     def get_logs(self, *levels):
         """Return all log messages with level in *levels*.
 
-        Without explicit levels given, returns all messages.
-        *levels* defaults to all levels.  For log calls with arguments (i.e.
-        logger.info('bla bla %s', arg)), the messages
-        Returns a list.
+        Without explicit levels given, returns all messages.  *levels* defaults
+        to all levels.  For log calls with arguments (i.e.
+        logger.info('bla bla %r', arg)), the messages will be formatted before
+        being returned (e.g. "bla bla 'thing'").
+
+        Returns a list.  Automatically flushes the loghandler after being
+        called.
 
         Example: self.get_logs(logging.WARN, logging.DEBUG).
         """
         if not levels:
-            return [log.getMessage() for log in self.loghandler.buffer]
-        return [log.getMessage() for log in self.loghandler.buffer
-                if log.levelno in levels]
+            messages = [log.getMessage() for log in self.loghandler.buffer]
+        else:
+            messages = [log.getMessage() for log in self.loghandler.buffer
+                        if log.levelno in levels]
+        self.loghandler.flush()
+        return messages
 
 
 class TempdirManager:
diff --git a/Lib/packaging/tests/test_command_check.py b/Lib/packaging/tests/test_command_check.py
index 8b32673..271e457 100644
--- a/Lib/packaging/tests/test_command_check.py
+++ b/Lib/packaging/tests/test_command_check.py
@@ -36,7 +36,6 @@ class CheckTestCase(support.LoggingCatcher,
         # now let's add the required fields
         # and run it again, to make sure we don't get
         # any warning anymore
-        self.loghandler.flush()
         metadata = {'home_page': 'xxx', 'author': 'xxx',
                     'author_email': 'xxx',
                     'name': 'xxx', 'version': '4.2',
@@ -50,8 +49,10 @@ class CheckTestCase(support.LoggingCatcher,
         self.assertRaises(PackagingSetupError, self._run,
             {'name': 'xxx', 'version': 'xxx'}, **{'strict': 1})
 
-        # and of course, no error when all metadata fields are present
+        # clear warnings from the previous calls
         self.loghandler.flush()
+
+        # and of course, no error when all metadata fields are present
         cmd = self._run(metadata, strict=True)
         self.assertEqual([], self.get_logs(logging.WARNING))
 
@@ -70,7 +71,6 @@ class CheckTestCase(support.LoggingCatcher,
                     'name': 'xxx', 'version': '4.2',
                     'requires_python': '2.4',
                     }
-        self.loghandler.flush()
         cmd = self._run(metadata)
         self.assertEqual([], self.get_logs(logging.WARNING))
 
@@ -85,9 +85,11 @@ class CheckTestCase(support.LoggingCatcher,
         self.assertRaises(PackagingSetupError, self._run, metadata,
             **{'strict': 1})
 
+        # clear warnings from the previous calls
+        self.loghandler.flush()
+
         # now with correct version format again
         metadata['version'] = '4.2'
-        self.loghandler.flush()
         cmd = self._run(metadata, strict=True)
         self.assertEqual([], self.get_logs(logging.WARNING))
 
@@ -100,7 +102,6 @@ class CheckTestCase(support.LoggingCatcher,
         cmd.check_restructuredtext()
         self.assertEqual(len(self.get_logs(logging.WARNING)), 1)
 
-        self.loghandler.flush()
         pkg_info, dist = self.create_dist(description='title\n=====\n\ntest')
         cmd = check(dist)
         cmd.check_restructuredtext()
@@ -123,6 +124,17 @@ class CheckTestCase(support.LoggingCatcher,
         cmd.check_hooks_resolvable()
         self.assertEqual(len(self.get_logs(logging.WARNING)), 1)
 
+    def test_warn(self):
+        _, dist = self.create_dist()
+        cmd = check(dist)
+        self.assertEqual([], self.get_logs())
+        cmd.warn('hello')
+        self.assertEqual(['check: hello'], self.get_logs())
+        cmd.warn('hello %s', 'world')
+        self.assertEqual(['check: hello world'], self.get_logs())
+        cmd.warn('hello %s %s', 'beautiful', 'world')
+        self.assertEqual(['check: hello beautiful world'], self.get_logs())
+
 
 def test_suite():
     return unittest.makeSuite(CheckTestCase)
diff --git a/Lib/packaging/tests/test_manifest.py b/Lib/packaging/tests/test_manifest.py
index 9fb8b63..e0bcbbc 100644
--- a/Lib/packaging/tests/test_manifest.py
+++ b/Lib/packaging/tests/test_manifest.py
@@ -50,9 +50,6 @@ class ManifestTestCase(support.TempdirManager,
         for warning in warnings:
             self.assertIn('no files found matching', warning)
 
-        # reset logs for the next assert
-        self.loghandler.flush()
-
         # manifest also accepts file-like objects
         with open(MANIFEST) as f:
             manifest.read_template(f)