[Python-checkins] cpython (2.7): Issue #26014: Guide 2.7 users to the new packaging documentation:
ned.deily
python-checkins at python.org
Sun Jun 5 20:40:42 EDT 2016
https://hg.python.org/cpython/rev/71fc5b246f5b
changeset: 101757:71fc5b246f5b
branch: 2.7
parent: 101754:db24d51c69d3
user: Ned Deily <nad at python.org>
date: Sun Jun 05 17:35:43 2016 -0700
summary:
Issue #26014: Guide 2.7 users to the new packaging documentation:
- the top-level 2.7 docs page now links to the newer doc pages
(installing and distribution) rather than the legacy ones
- the legacy install and distutils pages are now labeled as "legacy"
- the library/distutils page is updated to match the 3.x version
- "See also" links to the new docs are now provided in the legacy pages
- links to setuptools documentation have been updated
(original patch by Susan Sun)
files:
Doc/distributing/index.rst | 2 +-
Doc/distutils/index.rst | 11 +++-
Doc/install/index.rst | 11 +++-
Doc/library/distutils.rst | 40 +++++++++-----
Doc/tools/templates/indexcontent.html | 8 +-
Misc/NEWS | 6 ++
6 files changed, 53 insertions(+), 25 deletions(-)
diff --git a/Doc/distributing/index.rst b/Doc/distributing/index.rst
--- a/Doc/distributing/index.rst
+++ b/Doc/distributing/index.rst
@@ -61,7 +61,7 @@
extensions, to be installed on a system without needing to be built
locally.
-.. _setuptools: https://setuptools.pypa.io/en/latest/setuptools.html
+.. _setuptools: https://setuptools.readthedocs.io/en/latest/
.. _wheel: https://wheel.readthedocs.org
Open source licensing and collaboration
diff --git a/Doc/distutils/index.rst b/Doc/distutils/index.rst
--- a/Doc/distutils/index.rst
+++ b/Doc/distutils/index.rst
@@ -1,12 +1,17 @@
.. _distutils-index:
-###############################
- Distributing Python Modules
-###############################
+##############################################
+ Distributing Python Modules (Legacy version)
+##############################################
:Authors: Greg Ward, Anthony Baxter
:Email: distutils-sig at python.org
+.. seealso::
+
+ :ref:`distributing-index`
+ The up to date module distribution documentations
+
This document describes the Python Distribution Utilities ("Distutils") from
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
diff --git a/Doc/install/index.rst b/Doc/install/index.rst
--- a/Doc/install/index.rst
+++ b/Doc/install/index.rst
@@ -2,14 +2,19 @@
.. _install-index:
-*****************************
- Installing Python Modules
-*****************************
+********************************************
+ Installing Python Modules (Legacy version)
+********************************************
:Author: Greg Ward
.. TODO: Fill in XXX comments
+.. seealso::
+
+ :ref:`installing-index`
+ The up to date module installation documentations
+
.. 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.
diff --git a/Doc/library/distutils.rst b/Doc/library/distutils.rst
--- a/Doc/library/distutils.rst
+++ b/Doc/library/distutils.rst
@@ -1,10 +1,9 @@
-
:mod:`distutils` --- Building and installing Python modules
===========================================================
.. module:: distutils
- :synopsis: Support for building and installing Python modules into an existing Python
- installation.
+ :synopsis: Support for building and installing Python modules into an
+ existing Python installation.
.. sectionauthor:: Fred L. Drake, Jr. <fdrake at acm.org>
@@ -13,18 +12,31 @@
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:
+Most Python users will *not* want to use this module directly, but instead
+use the cross-version tools maintained by the Python Packaging Authority. In
+particular,
+`setuptools <https://setuptools.readthedocs.io/en/latest/>`__ 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
-.. seealso::
+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 <https://packaging.python.org>`_ for more
+information.
- :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.
+For the benefits of packaging tool authors and users seeking a deeper
+understanding of the details of the current packaging and distribution
+system, the legacy :mod:`distutils` based user documentation and API
+reference remain available:
- :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.
-
+* :ref:`install-index`
+* :ref:`distutils-index`
diff --git a/Doc/tools/templates/indexcontent.html b/Doc/tools/templates/indexcontent.html
--- a/Doc/tools/templates/indexcontent.html
+++ b/Doc/tools/templates/indexcontent.html
@@ -16,14 +16,14 @@
<p class="biglink"><a class="biglink" href="{{ pathto("howto/index") }}">{% trans %}Python HOWTOs{% endtrans %}</a><br/>
<span class="linkdescr">{% trans %}in-depth documents on specific topics{% endtrans %}</span></p>
</td><td width="50%">
+ <p class="biglink"><a class="biglink" href="{{ pathto("installing/index") }}">{% trans %}Installing Python Modules{% endtrans %}</a><br/>
+ <span class="linkdescr">{% trans %}installing from the Python Package Index & other sources{% endtrans %}</span></p>
+ <p class="biglink"><a class="biglink" href="{{ pathto("distributing/index") }}">{% trans %}Distributing Python Modules{% endtrans %}</a><br/>
+ <span class="linkdescr">{% trans %}publishing modules for installation by others{% endtrans %}</span></p>
<p class="biglink"><a class="biglink" href="{{ pathto("extending/index") }}">{% trans %}Extending and Embedding{% endtrans %}</a><br/>
<span class="linkdescr">{% trans %}tutorial for C/C++ programmers{% endtrans %}</span></p>
<p class="biglink"><a class="biglink" href="{{ pathto("c-api/index") }}">{% trans %}Python/C API{% endtrans %}</a><br/>
<span class="linkdescr">{% trans %}reference for C/C++ programmers{% endtrans %}</span></p>
- <p class="biglink"><a class="biglink" href="{{ pathto("install/index") }}">{% trans %}Installing Python Modules{% endtrans %}</a><br/>
- <span class="linkdescr">{% trans %}information for installers & sys-admins{% endtrans %}</span></p>
- <p class="biglink"><a class="biglink" href="{{ pathto("distutils/index") }}">{% trans %}Distributing Python Modules{% endtrans %}</a><br/>
- <span class="linkdescr">{% trans %}sharing modules with others{% endtrans %}</span></p>
<p class="biglink"><a class="biglink" href="{{ pathto("faq/index") }}">{% trans %}FAQs{% endtrans %}</a><br/>
<span class="linkdescr">{% trans %}frequently asked questions (with answers!){% endtrans %}</span></p>
</td></tr>
diff --git a/Misc/NEWS b/Misc/NEWS
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -293,6 +293,12 @@
functions together, and add more details such as what underlying Readline
functions and variables are accessed.
+- Issue #26014: Guide users to the newer packaging documentation as was done
+ for Python 3.x. In particular, the top-level 2.7 documentation page now
+ links to the newer installer and distributions pages rather than the
+ legacy install and Distutils pages; these are still linked to in the
+ library/distutils doc page.
+
Tests
-----
--
Repository URL: https://hg.python.org/cpython
More information about the Python-checkins
mailing list