# HG changeset patch # User Nick Coghlan # Date 1393241704 -36000 # Mon Feb 24 21:35:04 2014 +1000 # Branch issue19407_installer_docs # Node ID 8f60fbefe92e3152e37fb556c379e40ec1dcb995 # Parent 0909f73cfa3a28f54159adc1fc184adfa0c6ad8b Issue #19407: PEP 453 packaging docs updates - adds new Installing and Distributing guides - new guides are referenced from main index page *above* the C API related guides (Installing now gets pride of place at the top of the right hand column) - legacy guides are retained (they contain unique info on distutils internals), but are now only referenced from distutils docs and from other locations that need the detailed description of the --user install scheme - adjusts the embedding & extending guide to strongly encourage the use of third party tools - updates What's New entry for PEP 453 diff -r 0909f73cfa3a -r 8f60fbefe92e Doc/conf.py --- a/Doc/conf.py Sat Mar 08 16:36:37 2014 +1000 +++ b/Doc/conf.py Mon Feb 24 21:35:04 2014 +1000 @@ -120,11 +120,11 @@ latex_documents = [ ('c-api/index', 'c-api.tex', 'The Python/C API', _stdauthor, 'manual'), - ('distutils/index', 'distutils.tex', + ('distributing/index', 'distutils.tex', 'Distributing Python Modules', _stdauthor, 'manual'), ('extending/index', 'extending.tex', 'Extending and Embedding Python', _stdauthor, 'manual'), - ('install/index', 'install.tex', + ('installing/index', 'install.tex', 'Installing Python Modules', _stdauthor, 'manual'), ('library/index', 'library.tex', 'The Python Library Reference', _stdauthor, 'manual'), diff -r 0909f73cfa3a -r 8f60fbefe92e Doc/contents.rst --- a/Doc/contents.rst Sat Mar 08 16:36:37 2014 +1000 +++ b/Doc/contents.rst Mon Feb 24 21:35:04 2014 +1000 @@ -11,8 +11,8 @@ library/index.rst extending/index.rst c-api/index.rst - distutils/index.rst - install/index.rst + distributing/index.rst + installing/index.rst howto/index.rst faq/index.rst glossary.rst @@ -21,3 +21,11 @@ bugs.rst copyright.rst license.rst + +.. include legacy packaging docs in build + +.. toctree:: + :hidden: + + distutils/index.rst + install/index.rst diff -r 0909f73cfa3a -r 8f60fbefe92e Doc/distributing/index.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Doc/distributing/index.rst Mon Feb 24 21:35:04 2014 +1000 @@ -0,0 +1,15 @@ +.. _distributing-index: + +############################### + Distributing Python Modules +############################### + +:Email: distutils-sig@python.org + +Things to cover here: + +- Link to http://packaging.python.org/en/latest/tutorial.html#creating-your-own-project +- Link to http://packaging.python.org/en/latest/tutorial.html#building-uploading-your-project-to-pypi +- the Python Package Index (uploader perspective) +- the Python Packaging Authority +- the Python Packaging User Guide diff -r 0909f73cfa3a -r 8f60fbefe92e Doc/distutils/index.rst --- a/Doc/distutils/index.rst Sat Mar 08 16:36:37 2014 +1000 +++ b/Doc/distutils/index.rst Mon Feb 24 21:35:04 2014 +1000 @@ -1,8 +1,8 @@ .. _distutils-index: -############################### - Distributing Python Modules -############################### +############################################## + Distributing Python Modules (Legacy version) +############################################## :Authors: Greg Ward, Anthony Baxter :Email: distutils-sig@python.org diff -r 0909f73cfa3a -r 8f60fbefe92e Doc/extending/index.rst --- a/Doc/extending/index.rst Sat Mar 08 16:36:37 2014 +1000 +++ b/Doc/extending/index.rst Mon Feb 24 21:35:04 2014 +1000 @@ -21,14 +21,31 @@ 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 - `__ - in the Python Packaging User Guide for more information. +Recommended third party tools +============================= +This guide only covers the basic tools for creating extensions provided +as part of this version of CPython. Third party tools like Cython, +``cffi``, SWIG and Numba offer both simpler and more sophisticated +approaches to creating C and C++ extensions for Python. + +.. seealso:: + + `Python Packaging User Guide: Binary Extensions `_ + The Python Packaging User Guide not only covers several available + tools that simplify the creation of binary extensions, but also + discusses the various reasons why creating an extension module may be + desirable in the first place. + + +Creating extensions without third party tools +============================================= + +This section of the guide covers creating C and C++ extensions without +assistance from third party tools. It is intended primarily for creators +of those tools, rather than being a recommended way to create your own +C extensions. .. toctree:: :maxdepth: 2 @@ -38,4 +55,17 @@ newtypes.rst building.rst windows.rst + +Embedding the CPython runtime in a larger application +===================================================== + +Sometimes, rather than creating an extension that runs inside the Python +interpreter as the main application, it is desirable to instead embed +the CPython runtime inside a larger application. This section covers +some of the details involved in doing that successfully. + +.. toctree:: + :maxdepth: 2 + :numbered: + embedding.rst diff -r 0909f73cfa3a -r 8f60fbefe92e Doc/install/index.rst --- a/Doc/install/index.rst Sat Mar 08 16:36:37 2014 +1000 +++ b/Doc/install/index.rst Mon Feb 24 21:35:04 2014 +1000 @@ -2,9 +2,9 @@ .. _install-index: -***************************** - Installing Python Modules -***************************** +******************************************** + Installing Python Modules (Legacy version) +******************************************** :Author: Greg Ward diff -r 0909f73cfa3a -r 8f60fbefe92e Doc/installing/index.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Doc/installing/index.rst Mon Feb 24 21:35:04 2014 +1000 @@ -0,0 +1,35 @@ +.. highlightlang:: none + +.. _installing-index: + +***************************** + Installing Python Modules +***************************** + +:Email: distutils-sig@python.org + + +Things to cover here: + +- pip basics (and a link to http://packaging.python.org/en/latest/tutorial.html#installing-python-packages) +- venv (since the packaging user guide focuses on virtualenv) +- user installs +- key platform specific behaviours and considerations (mostly about avoiding + installing into the system Python on Linux, as well as the current lack + of pre-built binaries there with the default tools) +- the Python Package Index (downloader perspective) +- the Python Packaging Authority +- the Python Packaging User Guide + + +How do I ...? +============= + +These are quick answers for some common tasks. + +.. installing-per-user-installation: + +Install packages just for the current user +------------------------------------------ + +Use the ``--user`` option. diff -r 0909f73cfa3a -r 8f60fbefe92e Doc/library/distutils.rst --- a/Doc/library/distutils.rst Sat Mar 08 16:36:37 2014 +1000 +++ b/Doc/library/distutils.rst Mon Feb 24 21:35:04 2014 +1000 @@ -12,14 +12,15 @@ 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. +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. -User documentation and API reference are provided in another document: +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: -.. 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. It also contains - instructions for end-users wanting to install a distutils-based package, - :ref:`install-index`. +* :ref:`install-index` +* :ref:`distutils-index` diff -r 0909f73cfa3a -r 8f60fbefe92e Doc/library/ensurepip.rst --- a/Doc/library/ensurepip.rst Sat Mar 08 16:36:37 2014 +1000 +++ b/Doc/library/ensurepip.rst Mon Feb 24 21:35:04 2014 +1000 @@ -28,7 +28,7 @@ .. seealso:: - :ref:`install-index` + :ref:`installing-index` The end user guide for installing Python packages :pep:`453`: Explicit bootstrapping of pip in Python installations diff -r 0909f73cfa3a -r 8f60fbefe92e Doc/tools/sphinxext/indexcontent.html --- a/Doc/tools/sphinxext/indexcontent.html Sat Mar 08 16:36:37 2014 +1000 +++ b/Doc/tools/sphinxext/indexcontent.html Mon Feb 24 21:35:04 2014 +1000 @@ -16,14 +16,14 @@

Python HOWTOs
in-depth documents on specific topics

+

Installing Python Modules
+ installing from the Python Package Index & other sources

+

Distributing Python Modules
+ publishing modules for installation by others

Extending and Embedding
tutorial for C/C++ programmers

Python/C API
reference for C/C++ programmers

-

Installing Python Modules
- information for installers & sys-admins

-

Distributing Python Modules
- sharing modules with others

FAQs
frequently asked questions (with answers!)

diff -r 0909f73cfa3a -r 8f60fbefe92e Doc/tutorial/whatnow.rst --- a/Doc/tutorial/whatnow.rst Sat Mar 08 16:36:37 2014 +1000 +++ b/Doc/tutorial/whatnow.rst Mon Feb 24 21:35:04 2014 +1000 @@ -21,8 +21,8 @@ and many other tasks. Skimming through the Library Reference will give you an idea of what's available. -* :ref:`install-index` explains how to install external modules written by other - Python users. +* :ref:`installing-index` explains how to install additional modules written + by other Python users. * :ref:`reference-index`: A detailed explanation of Python's syntax and semantics. It's heavy reading, but is useful as a complete guide to the diff -r 0909f73cfa3a -r 8f60fbefe92e Doc/using/windows.rst --- a/Doc/using/windows.rst Sat Mar 08 16:36:37 2014 +1000 +++ b/Doc/using/windows.rst Mon Feb 24 21:35:04 2014 +1000 @@ -11,6 +11,10 @@ This document aims to give an overview of Windows-specific behaviour you should know about when using Python on Microsoft Windows. +.. XXX (ncoghlan) + + This looks rather stale to me... + Installing Python ================= diff -r 0909f73cfa3a -r 8f60fbefe92e Doc/whatsnew/3.4.rst --- a/Doc/whatsnew/3.4.rst Sat Mar 08 16:36:37 2014 +1000 +++ b/Doc/whatsnew/3.4.rst Mon Feb 24 21:35:04 2014 +1000 @@ -164,6 +164,9 @@ PEP 453: Explicit Bootstrapping of PIP in Python Installations -------------------------------------------------------------- +Bootstrapping pip by default +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + The new :mod:`ensurepip` module (defined in :pep:`453`) provides a standard cross-platform mechanism to bootstrap the pip installer into Python installations and virtual environments. @@ -191,6 +194,22 @@ __ http://www.python.org/dev/peps/pep-0453/#recommendations-for-downstream-distributors + +Documentation changes +~~~~~~~~~~~~~~~~~~~~~ + +As part of this change, the :ref:`installing-index` and +:ref:`distributing-index` sections of the documentation have been +completely redesigned as short getting started and FAQ documents. Most +packaging documentation has now been moved out to the Python Packaging +Authority maintained `Python Packaging User Guide +`__ and the documentation of the individual +projects. + +However, as this migration is currently still incomplete, the legacy +versions of those guides remaining available as :ref:`install-index` +and :ref:`distutils-index`. + .. note:: To avoid conflicts between parallel Python 2 and Python 3 installations,