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,
+Installing gunicorn is as easy as ``sudo pip install gunicorn``. For more
-see the `gunicorn documentation`_.
+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
+  and installing the package from the Sphinx Web site, or with ``pip``:
-  ``easy_install``:
 
   .. 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`_.
+    If you don't have ``pip``, follow the the :ref:`installation instructions
-
+    <installing-official-release>` to install it.
-.. _setuptools: http://pypi.python.org/pypi/setuptools
 
 .. _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
+         postgresql-server-dev-8.4 python-psycopg2
-    $ sudo easy_install Django
 
 .. _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
+        postgresql-server-dev-8.3 python-psycopg2
-
-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
 
 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,11 +437,11 @@ 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``,
+1. Install the `py-bcrypt`_ library (probably by running ``sudo pip install
-       ``easy_install py-bcrypt``, or downloading the library and installing
+   py-bcrypt``, or downloading the library and installing it with ``python
-       it with ``python setup.py install``).
+   setup.py install``).
 
-    2. Modify :setting:`PASSWORD_HASHERS` to list ``BCryptPasswordHasher``
+2. Modify :setting:`PASSWORD_HASHERS` to list ``BCryptPasswordHasher``
    first. That is, in your settings file, you'd put::
 
         PASSWORD_HASHERS = (
@@ -481,7 +481,7 @@ 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
 
@@ -494,7 +494,7 @@ default PDKDF2 algorithm:
    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',

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
+Check the :doc:`distribution specific notes </misc/distributions>` to see if
-platform/distribution provides official Django packages/installers.
+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``,
+2. Untar the downloaded file (e.g. ``tar xzvf Django-X.Y.tar.gz``,
-   where ``NNN`` is the version number of the latest release).
+   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
+4. If you're using Linux, Mac OS X or some other flavor of Unix, enter the
-   the command ``sudo python setup.py install`` at the shell prompt.
+   command ``sudo python setup.py install`` at the shell prompt. If you're
-   If you're using Windows, start up a command shell with administrator
+   using Windows, start up a command shell with administrator privileges and
-   privileges and run the command ``python setup.py install``.
+   run the command ``python setup.py install``. This will install Django in
-
+   your Python installation's ``site-packages`` directory.
-These commands 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/
 
@@ -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``.
 
-You *don't* have to run ``python setup.py install``, because you've already
+.. warning::
-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/