Merge pull request pypa#129 from qwcode/install_topics

push all the install examples into top-level sections

Author: qwcode

source/installing.rst

@@ -2,8 +2,8 @@
 Tutorial on Installing Packages
 ===============================
 
-:Page Status: Complete
-:Last Reviewed: 2014-09-30
+:Page Status: Incomplete
+:Last Reviewed: 2014-12-24
 
 .. contents:: Contents
    :local:
@@ -26,12 +26,8 @@ distribution, or another larger software distribution like Python itself.
 Setup for Installing Packages
 =============================
 
-This section describes the steps to follow before installing other
-Python packages.  You will want to install :ref:`pip` and
-:ref:`setuptools`, and in most cases, :ref:`virtualenv` (unless you're using
-`pyvenv`_).
-
-We recommend the following installation sequence:
+This section describes the steps to follow before installing other Python
+packages.
 
 1. Install :ref:`pip` and :ref:`setuptools`: [3]_
 
@@ -71,8 +67,8 @@ We recommend the following installation sequence:
 
 .. _`Creating and using Virtual Environments`:
 
-Virtual Environments
-====================
+Creating Virtual Environments
+=============================
 
 Python "Virtual Environments" allow Python :term:`packages <Distribution
 Package>` to be installed in an isolated location for a particular application,
@@ -124,15 +120,22 @@ For more information, see the `virtualenv <http://virtualenv.pypa.io>`_ docs or
 the `pyvenv`_ docs.
 
 
-Installing Python Packages
-==========================
+Use pip for Installing
+======================
+
+:ref:`pip` is the recommended installer.  Below, we'll cover the most common
+usage scenarios. For more detail, see the `pip docs <https://pip.pypa.io>`_,
+which includes a complete `Reference Guide
+<https://pip.pypa.io/en/latest/reference/index.html>`_.
 
-:ref:`pip` is the recommended installer, and supports various requirement forms
-and options.  For details, see the `pip docs
-<https://pip.pypa.io>`_.
+There are a few cases where you might want to use `easy_install
+<https://pip.pypa.io/en/latest/reference/index.html>`_ instead of pip.  For
+details, see the the :ref:`pip vs easy_install` breakdown in the :doc:`Advanced
+Topics <additional>` section.
 
-Examples
---------
+
+Installing from PyPI
+====================
 
 Install `SomeProject` and its dependencies from :term:`PyPI <Python Package
 Index (PyPI)>` using :ref:`pip:Requirement Specifiers`
@@ -144,21 +147,78 @@ Index (PyPI)>` using :ref:`pip:Requirement Specifiers`
  pip install 'SomeProject>=1.0.4'  # minimum version
 
 
-Install a list of requirements specified in a :ref:`Requirements File
-<pip:Requirements Files>`.
+Upgrading packages
+==================
+
+Upgrade an already installed `SomeProject` to the latest from PyPI.
 
 ::
 
- pip install -r requirements.txt
+ pip install --upgrade SomeProject
 
 
-Upgrade an already installed `SomeProject` to the latest from PyPI.
+Installing Cached Wheels
+========================
+
+:term:`Wheel` is a pre-built :term:`distribution <Distribution Package>` format that
+provides faster installation compared to :term:`Source Distributions (sdist)
+<Source Distribution (or "sdist")>`, especially when a project contains compiled
+extensions.
+
+As of v1.5, :ref:`pip` prefers :term:`wheels <Wheel>` over :term:`sdists <Source
+Distribution (or "sdist")>` when searching indexes.
+
+Although wheels are `becoming more common <http://pythonwheels.com>`_ on
+:term:`PyPI <Python Package Index (PyPI)>`, if you want all of your dependencies
+converted to wheel, do the following (assuming you're using a :ref:`Requirements
+File <pip:Requirements Files>`):
 
 ::
 
- pip install --upgrade SomeProject
+ pip wheel --wheel-dir=/local/wheels -r requirements.txt
+
+And then to install those requirements just using your local directory of wheels
+(and not from PyPI):
+
+::
+
+ pip install --no-index --find-links=/local/wheels -r requirements.txt
+
+
+:term:`Wheel` is intended to replace :term:`Eggs <Egg>`.  For a detailed
+comparison, see :ref:`Wheel vs Egg`.
+
+
+Installing to the User Site
+===========================
+
+To install :term:`packages <Distribution Package>` that are isolated to the
+current user, use the ``--user`` flag:
+
+::
+
+  pip install --user SomeProject
 
 
+For more information see the `User Installs
+<https://pip.readthedocs.org/en/latest/user_guide.html#user-installs>`_ section
+from the pip docs.
+
+
+Requirements files
+==================
+
+Install a list of requirements specified in a :ref:`Requirements File
+<pip:Requirements Files>`.
+
+::
+
+ pip install -r requirements.txt
+
+
+Installing from VCS
+===================
+
 Install a project from VCS in "editable" mode.  For a full breakdown of the
 syntax, see pip's section on :ref:`VCS Support <pip:VCS Support>`.
 
@@ -170,13 +230,8 @@ syntax, see pip's section on :ref:`VCS Support <pip:VCS Support>`.
  pip install -e git+https://git.repo/some_pkg.git@feature#egg=SomeProject  # from a branch
 
 
-Install a particular source archive file.
-
-::
-
- pip install ./downloads/SomeProject-1.0.4.tar.gz
- pip install http://my.package.repo/SomeProject-1.0.4.zip
-
+Installing from other Indexes
+=============================
 
 Install from an alternate index
 
@@ -193,76 +248,70 @@ Package Index (PyPI)>`
  pip install --extra-index-url http://my.package.repo/simple SomeProject
 
 
-Install from a local directory containing archives (and don't check :term:`PyPI
-<Python Package Index (PyPI)>`)
-
-::
 
- pip install --no-index --find-links=file:///local/dir/ SomeProject
- pip install --no-index --find-links=/local/dir/ SomeProject
- pip install --no-index --find-links=relative/dir/ SomeProject
+Installing from a local src tree
+================================
 
 
-Find pre-release and development versions, in addition to stable versions.  By
-default, pip only finds stable versions.
+Installing from local src in `Development Mode
+<http://pythonhosted.org/setuptools/setuptools.html#development-mode>`_, i.e. in
+such a way that the project appears to be installed, but yet is still editable
+from the src tree.
 
 ::
 
- pip install --pre SomeProject
+ pip install -e <path>
 
-Install a package with `setuptools extras`_.
-::
 
-  $ pip install SomePackage[PDF]
-  $ pip install SomePackage[PDF]==3.0
-  $ pip install -e .[PDF]==3.0  # editable project in current directory
+You can also normally from src
 
-Wheels
-------
+::
 
-:term:`Wheel` is a pre-built :term:`distribution <Distribution Package>` format that
-provides faster installation compared to :term:`Source Distributions (sdist)
-<Source Distribution (or "sdist")>`, especially when a project contains compiled
-extensions.
+ pip install <path>
 
-As of v1.5, :ref:`pip` prefers :term:`wheels <Wheel>` over :term:`sdists <Source
-Distribution (or "sdist")>` when searching indexes.
 
-Although wheels are `becoming more common <http://pythonwheels.com>`_ on
-:term:`PyPI <Python Package Index (PyPI)>`, if you want all of your dependencies
-converted to wheel, do the following (assuming you're using a :ref:`Requirements
-File <pip:Requirements Files>`):
+Installing from local archives
+==============================
+
+Install a particular source archive file.
 
 ::
 
- pip wheel --wheel-dir=/local/wheels -r requirements.txt
+ pip install ./downloads/SomeProject-1.0.4.tar.gz
 
-And then to install those requirements just using your local directory of wheels
-(and not from PyPI):
 
-::
+Install from a local directory containing archives (and don't check :term:`PyPI
+<Python Package Index (PyPI)>`)
 
- pip install --no-index --find-links=/local/wheels -r requirements.txt
+::
 
+ pip install --no-index --find-links=file:///local/dir/ SomeProject
+ pip install --no-index --find-links=/local/dir/ SomeProject
+ pip install --no-index --find-links=relative/dir/ SomeProject
 
-:term:`Wheel` is intended to replace :term:`Eggs <Egg>`.  For a detailed
-comparison, see :ref:`Wheel vs Egg`.
 
 
-User Installs
--------------
+Installing Prereleases
+======================
 
-To install :term:`packages <Distribution Package>` that are isolated to the
-current user, use the ``--user`` flag:
+Find pre-release and development versions, in addition to stable versions.  By
+default, pip only finds stable versions.
 
 ::
 
-  pip install --user SomeProject
+ pip install --pre SomeProject
 
 
-For more information see the `User Installs
-<https://pip.readthedocs.org/en/latest/user_guide.html#user-installs>`_ section
-from the pip docs.
+Installing Setuptools "Extras"
+==============================
+
+Install `setuptools extras`_.
+
+::
+
+  $ pip install SomePackage[PDF]
+  $ pip install SomePackage[PDF]==3.0
+  $ pip install -e .[PDF]==3.0  # editable project in current directory
 
 
 
@@ -288,5 +337,7 @@ from the pip docs.
        pre-installed, thereby making it an equal alternative to
        :ref:`virtualenv`.
 
+.. [5]
+
 .. _pyvenv: http://docs.python.org/3.4/library/venv.html
 .. _setuptools extras: http://packages.python.org/setuptools/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies