Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

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
  • Loading branch information...
commit c0e73a4909832e0db7cac5345128979a21529786 1 parent d636150
Aymeric Augustin authored
4  docs/README
@@ -5,9 +5,9 @@ Technically speaking, it uses ReST (reStructuredText) [1], and the Sphinx
5 5
 documentation system [2].  This allows it to be built into other forms for
6 6
 easier viewing and browsing.
7 7
 
8  
-To create an HTML version of the docs on a Unix machine (Linux or Mac):
  8
+To create an HTML version of the docs:
9 9
 
10  
-* Install Sphinx (using ``easy_install Sphinx`` or some other method)
  10
+* Install Sphinx (using ``sudo pip install Sphinx`` or some other method)
11 11
 
12 12
 * In this docs/ directory, type ``make html`` (or ``make.bat html`` on
13 13
   Windows) at a shell prompt.
4  docs/howto/deployment/wsgi/gunicorn.txt
@@ -18,8 +18,8 @@ special `integration with Django`_.
18 18
 Installing Gunicorn
19 19
 ===================
20 20
 
21  
-Installing gunicorn is as easy as ``pip install gunicorn``. For more details,
22  
-see the `gunicorn documentation`_.
  21
+Installing gunicorn is as easy as ``sudo pip install gunicorn``. For more
  22
+details, see the `gunicorn documentation`_.
23 23
 
24 24
 .. _gunicorn documentation: http://gunicorn.org/install.html
25 25
 
8  docs/howto/deployment/wsgi/uwsgi.txt
@@ -14,13 +14,15 @@ Prerequisite: uWSGI
14 14
 
15 15
 The uWSGI wiki describes several `installation procedures`_. Using pip, the
16 16
 Python package manager, you can install any uWSGI version with a single
17  
-command. For example::
  17
+command. For example:
  18
+
  19
+.. code-block:: bash
18 20
 
19 21
     # Install current stable version.
20  
-    pip install uwsgi
  22
+    $ sudo pip install uwsgi
21 23
 
22 24
     # Or install LTS (long term support).
23  
-    pip install http://projects.unbit.it/downloads/uwsgi-lts.tar.gz
  25
+    $ sudo pip install http://projects.unbit.it/downloads/uwsgi-lts.tar.gz
24 26
 
25 27
 .. _installation procedures: http://projects.unbit.it/uwsgi/wiki/Install
26 28
 
2  docs/internals/contributing/writing-documentation.txt
@@ -29,7 +29,7 @@ __ http://sphinx.pocoo.org/
29 29
 __ http://docutils.sourceforge.net/
30 30
 
31 31
 To actually build the documentation locally, you'll currently need to install
32  
-Sphinx -- ``easy_install Sphinx`` should do the trick.
  32
+Sphinx -- ``sudo pip install Sphinx`` should do the trick.
33 33
 
34 34
 .. note::
35 35
 
5  docs/intro/whatsnext.txt
@@ -166,12 +166,11 @@ You can get a local copy of the HTML documentation following a few easy steps:
166 166
 
167 167
 * Django's documentation uses a system called Sphinx__ to convert from
168 168
   plain text to HTML. You'll need to install Sphinx by either downloading
169  
-  and installing the package from the Sphinx Web site, or by Python's
170  
-  ``easy_install``:
  169
+  and installing the package from the Sphinx Web site, or with ``pip``:
171 170
 
172 171
   .. code-block:: bash
173 172
 
174  
-        $ easy_install Sphinx
  173
+        $ sudo pip install Sphinx
175 174
 
176 175
 * Then, just use the included ``Makefile`` to turn the documentation into
177 176
   HTML:
24  docs/ref/contrib/gis/install.txt
@@ -40,7 +40,9 @@ Python and Django
40 40
 -----------------
41 41
 
42 42
 Because GeoDjango is included with Django, please refer to Django's
43  
-:doc:`installation instructions </intro/install>` for details on how to install.
  43
+:ref:`installation instructions <installing-official-release>` for details on
  44
+how to install.
  45
+
44 46
 
45 47
 .. _spatial_database:
46 48
 
@@ -837,13 +839,12 @@ psycopg2
837 839
 After you've installed the KyngChaos binaries and modified your ``PATH``, as
838 840
 described above, ``psycopg2`` may be installed using the following command::
839 841
 
840  
-    $ sudo python easy_install psycopg2
  842
+    $ sudo pip install psycopg2
841 843
 
842 844
 .. note::
843 845
 
844  
-   To use ``easy_install`` you'll need to install Python's `setuptools`_.
845  
-
846  
-.. _setuptools: http://pypi.python.org/pypi/setuptools
  846
+    If you don't have ``pip``, follow the the :ref:`installation instructions
  847
+    <installing-official-release>` to install it.
847 848
 
848 849
 .. _pysqlite2_kyngchaos:
849 850
 
@@ -961,8 +962,7 @@ Ubuntu 10.04 uses PostGIS 1.4, while Ubuntu 10.10 uses PostGIS 1.5 (with
961 962
 geography support).  The installation commands are::
962 963
 
963 964
     $ sudo apt-get install binutils gdal-bin libproj-dev postgresql-8.4-postgis \
964  
-         postgresql-server-dev-8.4 python-psycopg2 python-setuptools
965  
-    $ sudo easy_install Django
  965
+         postgresql-server-dev-8.4 python-psycopg2
966 966
 
967 967
 .. _ibex:
968 968
 
@@ -972,13 +972,7 @@ geography support).  The installation commands are::
972 972
 Use the synaptic package manager to install the following packages::
973 973
 
974 974
     $ sudo apt-get install binutils gdal-bin postgresql-8.3-postgis \
975  
-        postgresql-server-dev-8.3 python-psycopg2 python-setuptools
976  
-
977  
-Afterwards, you may install Django with Python's ``easy_install`` script (the
978  
-Ubuntu package ``python-django`` uses an older version missing several
979  
-important bug fixes for GeoDjango)::
980  
-
981  
-    $ sudo easy_install Django
  975
+        postgresql-server-dev-8.3 python-psycopg2
982 976
 
983 977
 That's it!  For the curious, the required binary prerequisites packages are:
984 978
 
@@ -990,7 +984,6 @@ That's it!  For the curious, the required binary prerequisites packages are:
990 984
 * ``libgdal1-1.5.0``: for GDAL 1.5.0 library
991 985
 * ``proj``: for PROJ 4.6.0 -- but no datum shifting files, see note below
992 986
 * ``python-psycopg2``
993  
-* ``python-setuptools``: for ``easy_install``
994 987
 
995 988
 Optional packages to consider:
996 989
 
@@ -1060,7 +1053,6 @@ Required package information:
1060 1053
 * ``postgresql-8.1``
1061 1054
 * ``postgresql-server-dev-8.1``: for ``pg_config``
1062 1055
 * ``python-psycopg2``
1063  
-* ``python-setuptools``: for ``easy_install``
1064 1056
 
1065 1057
 Optional packages:
1066 1058
 
72  docs/topics/auth.txt
@@ -437,24 +437,24 @@ use it Django supports bcrypt with minimal effort.
437 437
 
438 438
 To use Bcrypt as your default storage algorithm, do the following:
439 439
 
440  
-    1. Install the `py-bcrypt`_ library (probably by running ``pip install py-bcrypt``,
441  
-       ``easy_install py-bcrypt``, or downloading the library and installing
442  
-       it with ``python setup.py install``).
443  
-
444  
-    2. Modify :setting:`PASSWORD_HASHERS` to list ``BCryptPasswordHasher``
445  
-       first. That is, in your settings file, you'd put::
446  
-
447  
-            PASSWORD_HASHERS = (
448  
-                'django.contrib.auth.hashers.BCryptPasswordHasher',
449  
-                'django.contrib.auth.hashers.PBKDF2PasswordHasher',
450  
-                'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',
451  
-                'django.contrib.auth.hashers.SHA1PasswordHasher',
452  
-                'django.contrib.auth.hashers.MD5PasswordHasher',
453  
-                'django.contrib.auth.hashers.CryptPasswordHasher',
454  
-            )
  440
+1. Install the `py-bcrypt`_ library (probably by running ``sudo pip install
  441
+   py-bcrypt``, or downloading the library and installing it with ``python
  442
+   setup.py install``).
  443
+
  444
+2. Modify :setting:`PASSWORD_HASHERS` to list ``BCryptPasswordHasher``
  445
+   first. That is, in your settings file, you'd put::
455 446
 
456  
-       (You need to keep the other entries in this list, or else Django won't
457  
-       be able to upgrade passwords; see below).
  447
+        PASSWORD_HASHERS = (
  448
+            'django.contrib.auth.hashers.BCryptPasswordHasher',
  449
+            'django.contrib.auth.hashers.PBKDF2PasswordHasher',
  450
+            'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',
  451
+            'django.contrib.auth.hashers.SHA1PasswordHasher',
  452
+            'django.contrib.auth.hashers.MD5PasswordHasher',
  453
+            'django.contrib.auth.hashers.CryptPasswordHasher',
  454
+        )
  455
+
  456
+   (You need to keep the other entries in this list, or else Django won't
  457
+   be able to upgrade passwords; see below).
458 458
 
459 459
 That's it -- now your Django install will use Bcrypt as the default storage
460 460
 algorithm.
@@ -481,30 +481,30 @@ you'll subclass the appropriate algorithm and override the ``iterations``
481 481
 parameters. For example, to increase the number of iterations used by the
482 482
 default PDKDF2 algorithm:
483 483
 
484  
-    1. Create a subclass of ``django.contrib.auth.hashers.PBKDF2PasswordHasher``::
  484
+1. Create a subclass of ``django.contrib.auth.hashers.PBKDF2PasswordHasher``::
485 485
 
486  
-            from django.contrib.auth.hashers import PBKDF2PasswordHasher
  486
+        from django.contrib.auth.hashers import PBKDF2PasswordHasher
487 487
 
488  
-            class MyPBKDF2PasswordHasher(PBKDF2PasswordHasher):
489  
-                """
490  
-                A subclass of PBKDF2PasswordHasher that uses 100 times more iterations.
491  
-                """
492  
-                iterations = PBKDF2PasswordHasher.iterations * 100
  488
+        class MyPBKDF2PasswordHasher(PBKDF2PasswordHasher):
  489
+            """
  490
+            A subclass of PBKDF2PasswordHasher that uses 100 times more iterations.
  491
+            """
  492
+            iterations = PBKDF2PasswordHasher.iterations * 100
493 493
 
494  
-       Save this somewhere in your project. For example, you might put this in
495  
-       a file like ``myproject/hashers.py``.
  494
+   Save this somewhere in your project. For example, you might put this in
  495
+   a file like ``myproject/hashers.py``.
496 496
 
497  
-    2. Add your new hasher as the first entry in :setting:`PASSWORD_HASHERS`::
  497
+2. Add your new hasher as the first entry in :setting:`PASSWORD_HASHERS`::
498 498
 
499  
-            PASSWORD_HASHERS = (
500  
-                'myproject.hashers.MyPBKDF2PasswordHasher',
501  
-                'django.contrib.auth.hashers.PBKDF2PasswordHasher',
502  
-                'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',
503  
-                'django.contrib.auth.hashers.BCryptPasswordHasher',
504  
-                'django.contrib.auth.hashers.SHA1PasswordHasher',
505  
-                'django.contrib.auth.hashers.MD5PasswordHasher',
506  
-                'django.contrib.auth.hashers.CryptPasswordHasher',
507  
-            )
  499
+        PASSWORD_HASHERS = (
  500
+            'myproject.hashers.MyPBKDF2PasswordHasher',
  501
+            'django.contrib.auth.hashers.PBKDF2PasswordHasher',
  502
+            'django.contrib.auth.hashers.PBKDF2SHA1PasswordHasher',
  503
+            'django.contrib.auth.hashers.BCryptPasswordHasher',
  504
+            'django.contrib.auth.hashers.SHA1PasswordHasher',
  505
+            'django.contrib.auth.hashers.MD5PasswordHasher',
  506
+            'django.contrib.auth.hashers.CryptPasswordHasher',
  507
+        )
508 508
 
509 509
 
510 510
 That's it -- now your Django install will use more iterations when it
72  docs/topics/install.txt
@@ -197,33 +197,62 @@ It's easy, no matter which way you choose.
197 197
 Installing a distribution-specific package
198 198
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
199 199
 
200  
-Check the :doc:`distribution specific notes </misc/distributions>` to see if your
201  
-platform/distribution provides official Django packages/installers.
  200
+Check the :doc:`distribution specific notes </misc/distributions>` to see if
  201
+your platform/distribution provides official Django packages/installers.
202 202
 Distribution-provided packages will typically allow for automatic installation
203 203
 of dependencies and easy upgrade paths.
204 204
 
205 205
 .. _installing-official-release:
206 206
 
207  
-Installing an official release
208  
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  207
+Installing an official release with ``pip``
  208
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  209
+
  210
+This is the recommended way to install Django.
  211
+
  212
+1. Install pip_. The easiest is to use the `standalone pip installer`_. If your
  213
+   distribution has ``pip`` already installed, make sure it isn't too outdated.
  214
+
  215
+2. (optional) Take a look at virtualenv_ and virtualenvwrapper_. These tools
  216
+   provide isolated Python environments, which are more practical than
  217
+   installing packages system-wide. They also allow installing packages
  218
+   without administrator privileges. It's up to you to decide if you want to
  219
+   learn and use them.
  220
+
  221
+3. If you're using Linux, Mac OS X or some other flavor of Unix, enter the
  222
+   command ``sudo pip install Django`` at the shell prompt. If you're using
  223
+   Windows, start up a command shell with administrator privileges and run
  224
+   the command ``pip install Django``. This will install Django in your Python
  225
+   installation's ``site-packages`` directory.
  226
+
  227
+   If you're using a virtualenv, you don't need ``sudo`` or administrator
  228
+   privileges, and this will install Django in the virtualenv's
  229
+   ``site-packages`` directory.
  230
+
  231
+
  232
+.. _pip: http://www.pip-installer.org/
  233
+.. _virtualenv: http://www.virtualenv.org/
  234
+.. _virtualenvwrapper: http://www.doughellmann.com/docs/virtualenvwrapper/
  235
+.. _standalone pip installer: http://www.pip-installer.org/en/latest/installing.html#using-the-installer
  236
+
  237
+Installing an official release manually
  238
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
209 239
 
210 240
 1. Download the latest release from our `download page`_.
211 241
 
212  
-2. Untar the downloaded file (e.g. ``tar xzvf Django-NNN.tar.gz``,
213  
-   where ``NNN`` is the version number of the latest release).
  242
+2. Untar the downloaded file (e.g. ``tar xzvf Django-X.Y.tar.gz``,
  243
+   where ``X.Y`` is the version number of the latest release).
214 244
    If you're using Windows, you can download the command-line tool
215 245
    bsdtar_ to do this, or you can use a GUI-based tool such as 7-zip_.
216 246
 
217  
-3. Change into the directory created in step 2 (e.g. ``cd Django-NNN``).
  247
+3. Change into the directory created in step 2 (e.g. ``cd Django-X.Y``).
218 248
 
219  
-4. If you're using Linux, Mac OS X or some other flavor of Unix, enter
220  
-   the command ``sudo python setup.py install`` at the shell prompt.
221  
-   If you're using Windows, start up a command shell with administrator
222  
-   privileges and run the command ``python setup.py install``.
223  
-
224  
-These commands will install Django in your Python installation's
225  
-``site-packages`` directory.
  249
+4. If you're using Linux, Mac OS X or some other flavor of Unix, enter the
  250
+   command ``sudo python setup.py install`` at the shell prompt. If you're
  251
+   using Windows, start up a command shell with administrator privileges and
  252
+   run the command ``python setup.py install``. This will install Django in
  253
+   your Python installation's ``site-packages`` directory.
226 254
 
  255
+.. _download page: http://www.djangoproject.com/download/
227 256
 .. _bsdtar: http://gnuwin32.sourceforge.net/packages/bsdtar.htm
228 257
 .. _7-zip: http://www.7-zip.org/
229 258
 
@@ -269,7 +298,7 @@ latest bug fixes and improvements, follow these instructions:
269 298
        # Git (requires version 1.6.6 or later)
270 299
        git clone https://github.com/django/django.git
271 300
        # or (works with all versions)
272  
-       git clone git://github.com/django/django.git       
  301
+       git clone git://github.com/django/django.git
273 302
 
274 303
        # Mercurial
275 304
        hg clone https://bitbucket.org/django/django
@@ -310,16 +339,19 @@ latest bug fixes and improvements, follow these instructions:
310 339
 
311 340
    On Windows systems, the same result can be achieved by copying the file
312 341
    ``django-trunk/django/bin/django-admin.py`` to somewhere on your system
313  
-   path, for example ``C:\Python24\Scripts``.
  342
+   path, for example ``C:\Python27\Scripts``.
  343
+
  344
+.. warning::
314 345
 
315  
-You *don't* have to run ``python setup.py install``, because you've already
316  
-carried out the equivalent actions in steps 3 and 4.
  346
+    You mustn't run ``sudo python setup.py install``, because you've already
  347
+    carried out the equivalent actions in steps 3 and 4. Furthermore, this is
  348
+    known to cause problems when updating to a more recent version of Django.
317 349
 
318 350
 When you want to update your copy of the Django source code, just run the
319 351
 command ``svn update`` from within the ``django-trunk`` directory. When you do
320  
-this, Subversion will automatically download any changes.
  352
+this, Subversion will automatically download any changes. The equivalent
  353
+command for Git is ``git pull``, and for Mercurial ``hg pull --update``.
321 354
 
322  
-.. _`download page`: http://www.djangoproject.com/download/
323 355
 .. _Subversion: http://subversion.tigris.org/
324 356
 .. _Git: http://git-scm.com/
325 357
 .. _Mercurial: http://mercurial.selenic.com/

0 notes on commit c0e73a4

Please sign in to comment.
Something went wrong with that request. Please try again.