From 3894ae20eac7e77969292fc0536633c648b8d043 Mon Sep 17 00:00:00 2001 From: Nick Coghlan Date: Sun, 26 Oct 2014 00:00:04 +1000 Subject: [PATCH] Issue #22711: improve links in new distribution docs - key term hyperlinks for distutils, setuptools & wheel - distutils landing page links directly to setuptools docs - short summary of setuptools benefits provided with link --- Doc/distributing/index.rst | 18 ++++++++++-------- Doc/library/distutils.rst | 22 +++++++++++++++++++--- 2 files changed, 29 insertions(+), 11 deletions(-) diff --git a/Doc/distributing/index.rst b/Doc/distributing/index.rst index 9146b81aad3..04606f15244 100644 --- a/Doc/distributing/index.rst +++ b/Doc/distributing/index.rst @@ -41,26 +41,28 @@ Key terms file format standards. They maintain a variety of tools, documentation and issue trackers on both `GitHub `__ and `BitBucket `__. -* ``distutils`` is the original build and distribution system first added to - the Python standard library in 1998. While direct use of ``distutils`` is - being phased out, it still laid the foundation for the current packaging +* :mod:`distutils` is the original build and distribution system first added + to the Python standard library in 1998. While direct use of :mod:`distutils` + is being phased out, it still laid the foundation for the current packaging and distribution infrastructure, and it not only remains part of the standard library, but its name lives on in other ways (such as the name of the mailing list used to coordinate Python packaging standards development). -* ``setuptools`` is a (largely) drop-in replacement for ``distutils`` first +* `setuptools`_ is a (largely) drop-in replacement for :mod:`distutils` first published in 2004. Its most notable addition over the unmodified - ``distutils`` tools was the ability to declare dependencies on other + :mod:`distutils` tools was the ability to declare dependencies on other packages. It is currently recommended as a more regularly updated - alternative to ``distutils`` that offers consistent support for more + alternative to :mod:`distutils` that offers consistent support for more recent packaging standards across a wide range of Python versions. -* ``wheel`` (in this context) is a project that adds the ``bdist_wheel`` - command to ``distutils``/``setuptools``. This produces a cross platform +* `wheel`_ (in this context) is a project that adds the ``bdist_wheel`` + command to :mod:`distutils`/`setuptools`_. This produces a cross platform binary packaging format (called "wheels" or "wheel files" and defined in :pep:`427`) that allows Python libraries, even those including binary extensions, to be installed on a system without needing to be built locally. +.. _setuptools: https://setuptools.pypa.io/en/latest/setuptools.html +.. _wheel: http://wheel.readthedocs.org Open source licensing and collaboration ======================================= diff --git a/Doc/library/distutils.rst b/Doc/library/distutils.rst index 8e3732bca5b..a7ad837cd91 100644 --- a/Doc/library/distutils.rst +++ b/Doc/library/distutils.rst @@ -13,9 +13,25 @@ additional modules into a Python installation. The new modules may be either collections of Python packages which include modules coded in both Python and C. Most Python users will *not* want to use this module directly, but instead -use the cross-version tools maintained by the Python Packaging Authority. -Refer to the `Python Packaging User Guide `_ -for more information. +use the cross-version tools maintained by the Python Packaging Authority. In +particular, +`setuptools `__ is an +enhanced alternative to :mod:`distutils` that provides: + +* support for declaring project dependencies +* additional mechanisms for configuring which files to include in source + releases (including plugins for integration with version control systems) +* the ability to declare project "entry points", which can be used as the + basis for application plugin systems +* the ability to automatically generate Windows command line executables at + installation time rather than needing to prebuild them +* consistent behaviour across all supported Python versions + +The recommended `pip `__ installer runs all +``setup.py`` scripts with ``setuptools``, even if the script itself only +imports ``distutils``. Refer to the +`Python Packaging User Guide `_ for more +information. For the benefits of packaging tool authors and users seeking a deeper understanding of the details of the current packaging and distribution