Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

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
This commit is contained in:
Nick Coghlan 2014-10-26 00:00:04 +10:00
parent 8b63d3af9f
commit 3894ae20ea
2 changed files with 29 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
Doc/distributing/index.rst
View File

@ -41,26 +41,28 @@ Key terms
file format standards. They maintain a variety of tools, documentation file format standards. They maintain a variety of tools, documentation
and issue trackers on both `GitHub <https://github.com/pypa>`__ and and issue trackers on both `GitHub <https://github.com/pypa>`__ and
`BitBucket <https://bitbucket.org/pypa/>`__. `BitBucket <https://bitbucket.org/pypa/>`__.
* ``distutils`` is the original build and distribution system first added to * :mod:`distutils` is the original build and distribution system first added
the Python standard library in 1998. While direct use of ``distutils`` is to the Python standard library in 1998. While direct use of :mod:`distutils`
being phased out, it still laid the foundation for the current packaging is being phased out, it still laid the foundation for the current packaging
and distribution infrastructure, and it not only remains part of the 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 standard library, but its name lives on in other ways (such as the name
of the mailing list used to coordinate Python packaging standards of the mailing list used to coordinate Python packaging standards
development). 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 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 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. recent packaging standards across a wide range of Python versions.
* ``wheel`` (in this context) is a project that adds the ``bdist_wheel`` * `wheel`_ (in this context) is a project that adds the ``bdist_wheel``
command to ``distutils``/``setuptools``. This produces a cross platform command to :mod:`distutils`/`setuptools`_. This produces a cross platform
binary packaging format (called "wheels" or "wheel files" and defined in binary packaging format (called "wheels" or "wheel files" and defined in
:pep:`427`) that allows Python libraries, even those including binary :pep:`427`) that allows Python libraries, even those including binary
extensions, to be installed on a system without needing to be built extensions, to be installed on a system without needing to be built
locally. locally.
.. _setuptools: https://setuptools.pypa.io/en/latest/setuptools.html
.. _wheel: http://wheel.readthedocs.org
Open source licensing and collaboration Open source licensing and collaboration
======================================= =======================================

22
Doc/library/distutils.rst
View File

@ -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. 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 Most Python users will *not* want to use this module directly, but instead
use the cross-version tools maintained by the Python Packaging Authority. use the cross-version tools maintained by the Python Packaging Authority. In
Refer to the `Python Packaging User Guide <http://packaging.python.org>`_ particular,
for more information. `setuptools <https://setuptools.pypa.io/en/latest/setuptools.html>`__ 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 <https://pip.pypa.io/>`__ installer runs all
``setup.py`` scripts with ``setuptools``, even if the script itself only
imports ``distutils``. Refer to the
`Python Packaging User Guide <http://packaging.python.org>`_ for more
information.
For the benefits of packaging tool authors and users seeking a deeper For the benefits of packaging tool authors and users seeking a deeper
understanding of the details of the current packaging and distribution understanding of the details of the current packaging and distribution