From c0e73a4909832e0db7cac5345128979a21529786 Mon Sep 17 00:00:00 2001 From: Aymeric Augustin Date: Sat, 3 Mar 2012 09:11:54 +0000 Subject: [PATCH] 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 | 4 +- docs/howto/deployment/wsgi/gunicorn.txt | 4 +- docs/howto/deployment/wsgi/uwsgi.txt | 8 ++- .../contributing/writing-documentation.txt | 2 +- docs/intro/whatsnext.txt | 5 +- docs/ref/contrib/gis/install.txt | 24 +++---- docs/topics/auth.txt | 68 +++++++++--------- docs/topics/install.txt | 72 +++++++++++++------ 8 files changed, 106 insertions(+), 81 deletions(-) diff --git a/docs/README b/docs/README index 323e191cce..b02499d738 100644 --- a/docs/README +++ b/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. diff --git a/docs/howto/deployment/wsgi/gunicorn.txt b/docs/howto/deployment/wsgi/gunicorn.txt index 609f7ccc86..ce9e54d4a6 100644 --- a/docs/howto/deployment/wsgi/gunicorn.txt +++ b/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 diff --git a/docs/howto/deployment/wsgi/uwsgi.txt b/docs/howto/deployment/wsgi/uwsgi.txt index 4af8e8a60f..209bdc9799 100644 --- a/docs/howto/deployment/wsgi/uwsgi.txt +++ b/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 diff --git a/docs/internals/contributing/writing-documentation.txt b/docs/internals/contributing/writing-documentation.txt index d61650a72e..c5a85764ba 100644 --- a/docs/internals/contributing/writing-documentation.txt +++ b/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:: diff --git a/docs/intro/whatsnext.txt b/docs/intro/whatsnext.txt index 20a5bd89d2..9f81f13f1b 100644 --- a/docs/intro/whatsnext.txt +++ b/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: diff --git a/docs/ref/contrib/gis/install.txt b/docs/ref/contrib/gis/install.txt index 419ed59369..06bee69244 100644 --- a/docs/ref/contrib/gis/install.txt +++ b/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 ` for details on how to install. +:ref:`installation instructions ` 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 + ` 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: diff --git a/docs/topics/auth.txt b/docs/topics/auth.txt index df843c8fe8..7c6b5a153d 100644 --- a/docs/topics/auth.txt +++ b/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``). +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:: +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', - ) + 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). + (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 diff --git a/docs/topics/install.txt b/docs/topics/install.txt index ae0f37176a..ab4a86084e 100644 --- a/docs/topics/install.txt +++ b/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 ` to see if your -platform/distribution provides official Django packages/installers. +Check the :doc:`distribution specific notes ` 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``. -You *don't* have to run ``python setup.py install``, because you've already -carried out the equivalent actions in steps 3 and 4. +.. warning:: + + 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/