Fixed #9995 -- Updated the installation instructions to recommend pip. Also fixed ReST errors. Refs #9112.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@17636 bcc190cf-cafb-0310-a4f2-bffc1f526a37

docs/README

@@ -5,9 +5,9 @@ Technically speaking, it uses ReST (reStructuredText) [1], and the Sphinx
 documentation system [2].  This allows it to be built into other forms for
 easier viewing and browsing.
 
-To create an HTML version of the docs on a Unix machine (Linux or Mac):
+To create an HTML version of the docs:
 
-* Install Sphinx (using ``easy_install Sphinx`` or some other method)
+* Install Sphinx (using ``sudo pip install Sphinx`` or some other method)
 
 * In this docs/ directory, type ``make html`` (or ``make.bat html`` on
   Windows) at a shell prompt.

docs/howto/deployment/wsgi/gunicorn.txt

@@ -18,8 +18,8 @@ special `integration with Django`_.
 Installing Gunicorn
 ===================
 
-Installing gunicorn is as easy as ``pip install gunicorn``. For more details,
-see the `gunicorn documentation`_.
+Installing gunicorn is as easy as ``sudo pip install gunicorn``. For more
+details, see the `gunicorn documentation`_.
 
 .. _gunicorn documentation: http://gunicorn.org/install.html
 

docs/howto/deployment/wsgi/uwsgi.txt

@@ -14,13 +14,15 @@ Prerequisite: uWSGI
 
 The uWSGI wiki describes several `installation procedures`_. Using pip, the
 Python package manager, you can install any uWSGI version with a single
-command. For example::
+command. For example:
+
+.. code-block:: bash
 
     # Install current stable version.
-    pip install uwsgi
+    $ sudo pip install uwsgi
 
     # Or install LTS (long term support).
-    pip install http://projects.unbit.it/downloads/uwsgi-lts.tar.gz
+    $ sudo pip install http://projects.unbit.it/downloads/uwsgi-lts.tar.gz
 
 .. _installation procedures: http://projects.unbit.it/uwsgi/wiki/Install
 

docs/internals/contributing/writing-documentation.txt

@@ -29,7 +29,7 @@ __ http://sphinx.pocoo.org/
 __ http://docutils.sourceforge.net/
 
 To actually build the documentation locally, you'll currently need to install
-Sphinx -- ``easy_install Sphinx`` should do the trick.
+Sphinx -- ``sudo pip install Sphinx`` should do the trick.
 
 .. note::
 

docs/intro/whatsnext.txt

@@ -166,12 +166,11 @@ You can get a local copy of the HTML documentation following a few easy steps:
 
 * Django's documentation uses a system called Sphinx__ to convert from
   plain text to HTML. You'll need to install Sphinx by either downloading
-  and installing the package from the Sphinx Web site, or by Python's
-  ``easy_install``:
+  and installing the package from the Sphinx Web site, or with ``pip``:
 
   .. code-block:: bash
 
-        $ easy_install Sphinx
+        $ sudo pip install Sphinx
 
 * Then, just use the included ``Makefile`` to turn the documentation into
   HTML:

docs/ref/contrib/gis/install.txt

@@ -40,7 +40,9 @@ Python and Django
 -----------------
 
 Because GeoDjango is included with Django, please refer to Django's
-:doc:`installation instructions </intro/install>` for details on how to install.
+:ref:`installation instructions <installing-official-release>` for details on
+how to install.
+
 
 .. _spatial_database:
 
@@ -837,13 +839,12 @@ psycopg2
 After you've installed the KyngChaos binaries and modified your ``PATH``, as
 described above, ``psycopg2`` may be installed using the following command::
 
-    $ sudo python easy_install psycopg2
+    $ sudo pip install psycopg2
 
 .. note::
 
-   To use ``easy_install`` you'll need to install Python's `setuptools`_.
-
-.. _setuptools: http://pypi.python.org/pypi/setuptools
+    If you don't have ``pip``, follow the the :ref:`installation instructions
+    <installing-official-release>` to install it.
 
 .. _pysqlite2_kyngchaos:
 
@@ -961,8 +962,7 @@ Ubuntu 10.04 uses PostGIS 1.4, while Ubuntu 10.10 uses PostGIS 1.5 (with
 geography support).  The installation commands are::
 
     $ sudo apt-get install binutils gdal-bin libproj-dev postgresql-8.4-postgis \
-         postgresql-server-dev-8.4 python-psycopg2 python-setuptools
-    $ sudo easy_install Django
+         postgresql-server-dev-8.4 python-psycopg2
 
 .. _ibex:
 
@@ -972,13 +972,7 @@ geography support).  The installation commands are::
 Use the synaptic package manager to install the following packages::
 
     $ sudo apt-get install binutils gdal-bin postgresql-8.3-postgis \
-        postgresql-server-dev-8.3 python-psycopg2 python-setuptools
-
-Afterwards, you may install Django with Python's ``easy_install`` script (the
-Ubuntu package ``python-django`` uses an older version missing several
-important bug fixes for GeoDjango)::
-
-    $ sudo easy_install Django
+        postgresql-server-dev-8.3 python-psycopg2
 
 That's it!  For the curious, the required binary prerequisites packages are:
 
@@ -990,7 +984,6 @@ That's it!  For the curious, the required binary prerequisites packages are:
 * ``libgdal1-1.5.0``: for GDAL 1.5.0 library
 * ``proj``: for PROJ 4.6.0 -- but no datum shifting files, see note below
 * ``python-psycopg2``
-* ``python-setuptools``: for ``easy_install``
 
 Optional packages to consider:
 
@@ -1060,7 +1053,6 @@ Required package information:
 * ``postgresql-8.1``
 * ``postgresql-server-dev-8.1``: for ``pg_config``
 * ``python-psycopg2``
-* ``python-setuptools``: for ``easy_install``
 
 Optional packages:
 

docs/topics/auth.txt

@@ -437,24 +437,24 @@ use it Django supports bcrypt with minimal effort.
 
 To use Bcrypt as your default storage algorithm, do the following:
 
-    1. Install the `py-bcrypt`_ library (probably by running ``pip install py-bcrypt``,
-       ``easy_install py-bcrypt``, or downloading the library and installing
-       it with ``python setup.py install``).
-
-    2. Modify :setting:`PASSWORD_HASHERS` to list ``BCryptPasswordHasher``
-       first. That is, in your settings file, you'd put::
-
-            PASSWORD_HASHERS = (
-                'django.contrib.auth.hashers.BCryptPasswordHasher',
-                'django.contrib.auth.hashers.PBKDF2PasswordHasher',
-                'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',
-                'django.contrib.auth.hashers.SHA1PasswordHasher',
-                'django.contrib.auth.hashers.MD5PasswordHasher',
-                'django.contrib.auth.hashers.CryptPasswordHasher',
-            )
+1. Install the `py-bcrypt`_ library (probably by running ``sudo pip install
+   py-bcrypt``, or downloading the library and installing it with ``python
+   setup.py install``).
+
+2. Modify :setting:`PASSWORD_HASHERS` to list ``BCryptPasswordHasher``
+   first. That is, in your settings file, you'd put::
 
-       (You need to keep the other entries in this list, or else Django won't
-       be able to upgrade passwords; see below).
+        PASSWORD_HASHERS = (
+            'django.contrib.auth.hashers.BCryptPasswordHasher',
+            'django.contrib.auth.hashers.PBKDF2PasswordHasher',
+            'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',
+            'django.contrib.auth.hashers.SHA1PasswordHasher',
+            'django.contrib.auth.hashers.MD5PasswordHasher',
+            'django.contrib.auth.hashers.CryptPasswordHasher',
+        )
+
+   (You need to keep the other entries in this list, or else Django won't
+   be able to upgrade passwords; see below).
 
 That's it -- now your Django install will use Bcrypt as the default storage
 algorithm.
@@ -481,30 +481,30 @@ you'll subclass the appropriate algorithm and override the ``iterations``
 parameters. For example, to increase the number of iterations used by the
 default PDKDF2 algorithm:
 
-    1. Create a subclass of ``django.contrib.auth.hashers.PBKDF2PasswordHasher``::
+1. Create a subclass of ``django.contrib.auth.hashers.PBKDF2PasswordHasher``::
 
-            from django.contrib.auth.hashers import PBKDF2PasswordHasher
+        from django.contrib.auth.hashers import PBKDF2PasswordHasher
 
-            class MyPBKDF2PasswordHasher(PBKDF2PasswordHasher):
-                """
-                A subclass of PBKDF2PasswordHasher that uses 100 times more iterations.
-                """
-                iterations = PBKDF2PasswordHasher.iterations * 100
+        class MyPBKDF2PasswordHasher(PBKDF2PasswordHasher):
+            """
+            A subclass of PBKDF2PasswordHasher that uses 100 times more iterations.
+            """
+            iterations = PBKDF2PasswordHasher.iterations * 100
 
-       Save this somewhere in your project. For example, you might put this in
-       a file like ``myproject/hashers.py``.
+   Save this somewhere in your project. For example, you might put this in
+   a file like ``myproject/hashers.py``.
 
-    2. Add your new hasher as the first entry in :setting:`PASSWORD_HASHERS`::
+2. Add your new hasher as the first entry in :setting:`PASSWORD_HASHERS`::
 
-            PASSWORD_HASHERS = (
-                'myproject.hashers.MyPBKDF2PasswordHasher',
-                'django.contrib.auth.hashers.PBKDF2PasswordHasher',
-                'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',
-                'django.contrib.auth.hashers.BCryptPasswordHasher',
-                'django.contrib.auth.hashers.SHA1PasswordHasher',
-                'django.contrib.auth.hashers.MD5PasswordHasher',
-                'django.contrib.auth.hashers.CryptPasswordHasher',
-            )
+        PASSWORD_HASHERS = (
+            'myproject.hashers.MyPBKDF2PasswordHasher',
+            'django.contrib.auth.hashers.PBKDF2PasswordHasher',
+            'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',
+            'django.contrib.auth.hashers.BCryptPasswordHasher',
+            'django.contrib.auth.hashers.SHA1PasswordHasher',
+            'django.contrib.auth.hashers.MD5PasswordHasher',
+            'django.contrib.auth.hashers.CryptPasswordHasher',
+        )
 
 
 That's it -- now your Django install will use more iterations when it

docs/topics/install.txt

@@ -197,33 +197,62 @@ It's easy, no matter which way you choose.
 Installing a distribution-specific package
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Check the :doc:`distribution specific notes </misc/distributions>` to see if your
-platform/distribution provides official Django packages/installers.
+Check the :doc:`distribution specific notes </misc/distributions>` to see if
+your platform/distribution provides official Django packages/installers.
 Distribution-provided packages will typically allow for automatic installation
 of dependencies and easy upgrade paths.
 
 .. _installing-official-release:
 
-Installing an official release
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Installing an official release with ``pip``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is the recommended way to install Django.
+
+1. Install pip_. The easiest is to use the `standalone pip installer`_. If your
+   distribution has ``pip`` already installed, make sure it isn't too outdated.
+
+2. (optional) Take a look at virtualenv_ and virtualenvwrapper_. These tools
+   provide isolated Python environments, which are more practical than
+   installing packages system-wide. They also allow installing packages
+   without administrator privileges. It's up to you to decide if you want to
+   learn and use them.
+
+3. If you're using Linux, Mac OS X or some other flavor of Unix, enter the
+   command ``sudo pip install Django`` at the shell prompt. If you're using
+   Windows, start up a command shell with administrator privileges and run
+   the command ``pip install Django``. This will install Django in your Python
+   installation's ``site-packages`` directory.
+
+   If you're using a virtualenv, you don't need ``sudo`` or administrator
+   privileges, and this will install Django in the virtualenv's
+   ``site-packages`` directory.
+
+
+.. _pip: http://www.pip-installer.org/
+.. _virtualenv: http://www.virtualenv.org/
+.. _virtualenvwrapper: http://www.doughellmann.com/docs/virtualenvwrapper/
+.. _standalone pip installer: http://www.pip-installer.org/en/latest/installing.html#using-the-installer
+
+Installing an official release manually
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 1. Download the latest release from our `download page`_.
 
-2. Untar the downloaded file (e.g. ``tar xzvf Django-NNN.tar.gz``,
-   where ``NNN`` is the version number of the latest release).
+2. Untar the downloaded file (e.g. ``tar xzvf Django-X.Y.tar.gz``,
+   where ``X.Y`` is the version number of the latest release).
    If you're using Windows, you can download the command-line tool
    bsdtar_ to do this, or you can use a GUI-based tool such as 7-zip_.
 
-3. Change into the directory created in step 2 (e.g. ``cd Django-NNN``).
+3. Change into the directory created in step 2 (e.g. ``cd Django-X.Y``).
 
-4. If you're using Linux, Mac OS X or some other flavor of Unix, enter
-   the command ``sudo python setup.py install`` at the shell prompt.
-   If you're using Windows, start up a command shell with administrator
-   privileges and run the command ``python setup.py install``.
-
-These commands will install Django in your Python installation's
-``site-packages`` directory.
+4. If you're using Linux, Mac OS X or some other flavor of Unix, enter the
+   command ``sudo python setup.py install`` at the shell prompt. If you're
+   using Windows, start up a command shell with administrator privileges and
+   run the command ``python setup.py install``. This will install Django in
+   your Python installation's ``site-packages`` directory.
 
+.. _download page: http://www.djangoproject.com/download/
 .. _bsdtar: http://gnuwin32.sourceforge.net/packages/bsdtar.htm
 .. _7-zip: http://www.7-zip.org/
 
@@ -269,7 +298,7 @@ latest bug fixes and improvements, follow these instructions:
        # Git (requires version 1.6.6 or later)
        git clone https://github.com/django/django.git
        # or (works with all versions)
-       git clone git://github.com/django/django.git       
+       git clone git://github.com/django/django.git
 
        # Mercurial
        hg clone https://bitbucket.org/django/django
@@ -310,16 +339,19 @@ latest bug fixes and improvements, follow these instructions:
 
    On Windows systems, the same result can be achieved by copying the file
    ``django-trunk/django/bin/django-admin.py`` to somewhere on your system
-   path, for example ``C:\Python24\Scripts``.
+   path, for example ``C:\Python27\Scripts``.
+
+.. warning::
 
-You *don't* have to run ``python setup.py install``, because you've already
-carried out the equivalent actions in steps 3 and 4.
+    You mustn't run ``sudo python setup.py install``, because you've already
+    carried out the equivalent actions in steps 3 and 4. Furthermore, this is
+    known to cause problems when updating to a more recent version of Django.
 
 When you want to update your copy of the Django source code, just run the
 command ``svn update`` from within the ``django-trunk`` directory. When you do
-this, Subversion will automatically download any changes.
+this, Subversion will automatically download any changes. The equivalent
+command for Git is ``git pull``, and for Mercurial ``hg pull --update``.
 
-.. _`download page`: http://www.djangoproject.com/download/
 .. _Subversion: http://subversion.tigris.org/
 .. _Git: http://git-scm.com/
 .. _Mercurial: http://mercurial.selenic.com/