Issue #19407: add Python Packaging User Guide notes

The stdlib docs for package distribution and building extensions
are rather dated, and that isn't expected to change for 2.7 and
3.3.

The Python Packaging User Guide isn't complete either, but it's
already a much better road map for new users than the existing
stdlib docs.

diff --git a/Doc/distutils/index.rst b/Doc/distutils/index.rst
index 1cd5f3c5dc6e2175b8e142b2d184c5142afccf54..1a6f04c87af8a2216d850f057de3425ef43e148a 100644 (file)
--- a/Doc/distutils/index.rst
+++ b/Doc/distutils/index.rst
@@ -12,6 +12,16 @@ 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.
 
+.. note::
+
+   This guide only covers the basic tools for building and distributing
+   extensions that are provided as part of this version of Python. Third
+   party tools offer easier to use and more secure alternatives. Refer to the
+   `quick recommendations section
+   <https://python-packaging-user-guide.readthedocs.org/en/latest/current.html>`__
+   in the Python Packaging User Guide for more information.
+
+
 .. toctree::
    :maxdepth: 2
    :numbered:

diff --git a/Doc/extending/index.rst b/Doc/extending/index.rst
index 61129439958522cef4d8393effb05098d7ac8a44..44a7f92c007b1a3cd0a4afc88f9db5c03350eeed 100644 (file)
--- a/Doc/extending/index.rst
+++ b/Doc/extending/index.rst
@@ -21,6 +21,15 @@ Python) that give the language its wide application range.
 For a detailed description of the whole Python/C API, see the separate
 :ref:`c-api-index`.
 
+.. note::
+
+   This guide only covers the basic tools for creating extensions provided
+   as part of this version of CPython. Third party tools may offer simpler
+   alternatives. Refer to the `binary extensions section
+   <https://python-packaging-user-guide.readthedocs.org/en/latest/extensions.html>`__
+   in the Python Packaging User Guide for more information.
+
+
 .. toctree::
    :maxdepth: 2
    :numbered:

diff --git a/Doc/install/index.rst b/Doc/install/index.rst
index 159f84816da4fe6fc32e585473e9a907b8777e15..a5a4c2147513da692903b8bbd22e7ea712ea1df0 100644 (file)
--- a/Doc/install/index.rst
+++ b/Doc/install/index.rst
@@ -20,12 +20,20 @@
    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 the Python Distribution Utilities ("Distutils") from the
+end-user's point-of-view, describing how to extend the capabilities of a
+standard Python installation by building and installing third-party Python
+modules and extensions.
 
-   This document describes the Python Distribution Utilities ("Distutils") from the
-   end-user's point-of-view, describing how to extend the capabilities of a
-   standard Python installation by building and installing third-party Python
-   modules and extensions.
+
+.. note::
+
+   This guide only covers the basic tools for installing extensions that are
+   provided as part of this version of Python. Third party tools offer easier
+   to use and more secure alternatives. Refer to the
+   `quick recommendations section
+   <https://python-packaging-user-guide.readthedocs.org/en/latest/current.html>`__
+   in the Python Packaging User Guide for more information.
 
 
 .. _inst-intro: