Fixed #25376 -- Required virtualenv in installation instructions.

Thanks Anjul Tyagi for some of the draft text.

1 files changed, 19 insertions, 128 deletions

diff --git a/docs/topics/install.txt b/docs/topics/install.txt
index 027dd5db31..2c4a422689 100644
--- a/docs/topics/install.txt
+++ b/docs/topics/install.txt
@@ -119,9 +119,9 @@ database queries, Django will need permission to create a test database.
 .. _MySQL: http://www.mysql.com/
 .. _psycopg2: http://initd.org/psycopg/
 .. _SQLite: http://www.sqlite.org/
-.. _pysqlite: http://trac.edgewall.org/wiki/PySqlite
 .. _cx_Oracle: http://cx-oracle.sourceforge.net/
 .. _Oracle: http://www.oracle.com/
+
 .. _removing-old-versions-of-django:
 
 Remove any old versions of Django
@@ -144,7 +144,6 @@ following at your shell prompt (not the interactive Python prompt):
 
     $ python -c "import django; print(django.__path__)"
 
-
 .. _install-django-code:
 
 Install the Django code
@@ -168,58 +167,20 @@ This is the recommended way to install Django.
    it's outdated. (If it's outdated, you'll know because installation won't
    work.)
 
-2. (optional) Take a look at virtualenv_ and virtualenvwrapper_. These tools
-   provide isolated Python environments, which are more practical than
-   installing packages systemwide. 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 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.
+2. Take a look at virtualenv_ and virtualenvwrapper_. These tools provide
+   isolated Python environments, which are more practical than installing
+   packages systemwide. They also allow installing packages without
+   administrator privileges. The :doc:`contributing tutorial
+   </intro/contributing>` walks through how to create a virtualenv on Python 3.
 
-   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.
+3. After you've created and activated a virtual environment, enter the command
+   ``pip install Django`` at the shell prompt.
 
 .. _pip: https://pip.pypa.io/
 .. _virtualenv: http://www.virtualenv.org/
 .. _virtualenvwrapper: http://virtualenvwrapper.readthedocs.org/en/latest/
 .. _standalone pip installer: https://pip.pypa.io/en/latest/installing.html#install-pip
 
-Installing an official release manually
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-1. Download the latest release from our `download page`_.
-
-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-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 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.
-
-   .. admonition:: Removing an old version
-
-       If you use this installation technique, it is particularly important
-       that you :ref:`remove any existing
-       installations<removing-old-versions-of-django>` of Django
-       first. Otherwise, you can end up with a broken installation that
-       includes files from previous versions that have since been removed from
-       Django.
-
-.. _download page: https://www.djangoproject.com/download/
-.. _bsdtar: http://gnuwin32.sourceforge.net/packages/bsdtar.htm
-.. _7-zip: http://www.7-zip.org/
-
 Installing a distribution-specific package
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -253,101 +214,31 @@ latest bug fixes and improvements, follow these instructions:
 1. Make sure that you have Git_ installed and that you can run its commands
    from a shell. (Enter ``git help`` at a shell prompt to test this.)
 
-2. Check out Django's main development branch (the 'trunk' or 'master') like
-   so:
+2. Check out Django's main development branch like so:
 
    .. code-block:: console
 
-        $ git clone git://github.com/django/django.git django-trunk
+        $ git clone git://github.com/django/django.git
 
-   This will create a directory ``django-trunk`` in your current directory.
+   This will create a directory ``django`` in your current directory.
 
 3. Make sure that the Python interpreter can load Django's code. The most
-   convenient way to do this is via pip_. Run the following command:
+   convenient way to do this is to use virtualenv_, virtualenvwrapper_, and
+   pip_. The :doc:`contributing tutorial </intro/contributing>` walks through
+   how to create a virtualenv on Python 3.
 
-   .. code-block:: console
+4. After setting up and activating the virtualenv, run the following command:
 
-        $ sudo pip install -e django-trunk/
+   .. code-block:: console
 
-   (If using a virtualenv_ you can omit ``sudo``.)
+        $ pip install -e django/
 
    This will make Django's code importable, and will also make the
    ``django-admin`` utility command available. In other words, you're all
    set!
 
-   If you don't have pip_ available, see the alternative instructions for
-   `installing the development version without pip`_.
-
-.. warning::
-
-    Don't run ``sudo python setup.py install``, because you've already
-    carried out the equivalent actions in step 3.
-
 When you want to update your copy of the Django source code, just run the
-command ``git pull`` from within the ``django-trunk`` directory. When you do
-this, Git will automatically download any changes.
+command ``git pull`` from within the ``django`` directory. When you do this,
+Git will automatically download any changes.
 
 .. _Git: http://git-scm.com/
-.. _`modify Python's search path`: https://docs.python.org/install/index.html#modifying-python-s-search-path
-.. _installing-the-development-version-without-pip:
-
-Installing the development version without pip
-----------------------------------------------
-
-If you don't have pip_, you can instead manually `modify Python's search
-path`_.
-
-First follow steps 1 and 2 above, so that you have a ``django-trunk`` directory
-with a checkout of Django's latest code in it. Then add a ``.pth`` file
-containing the full path to the ``django-trunk`` directory to your system's
-``site-packages`` directory. For example, on a Unix-like system:
-
-.. code-block:: console
-
-    $ echo WORKING-DIR/django-trunk > SITE-PACKAGES-DIR/django.pth
-
-In the above line, change ``WORKING-DIR/django-trunk`` to match the full path
-to your new ``django-trunk`` directory, and change ``SITE-PACKAGES-DIR`` to
-match the location of your system's ``site-packages`` directory.
-
-The location of the ``site-packages`` directory depends on the operating
-system, and the location in which Python was installed. To find your system's
-``site-packages`` location, execute the following:
-
-.. code-block:: console
-
-    $ python -c "from distutils.sysconfig import get_python_lib; print(get_python_lib())"
-
-(Note that this should be run from a shell prompt, not a Python interactive
-prompt.)
-
-Some Debian-based Linux distributions have separate ``site-packages``
-directories for user-installed packages, such as when installing Django from
-a downloaded tarball. The command listed above will give you the system's
-``site-packages``, the user's directory can be found in ``/usr/local/lib/``
-instead of ``/usr/lib/``.
-
-Next you need to make the ``django-admin.py`` utility available in your
-shell PATH.
-
-On Unix-like systems, create a symbolic link to the file
-``django-trunk/django/bin/django-admin`` in a directory on your system
-path, such as ``/usr/local/bin``. For example:
-
-.. code-block:: console
-
-    $ ln -s WORKING-DIR/django-trunk/django/bin/django-admin.py /usr/local/bin/
-
-(In the above line, change WORKING-DIR to match the full path to your new
-``django-trunk`` directory.)
-
-This simply lets you type ``django-admin.py`` from within any directory,
-rather than having to qualify the command with the full path to the file.
-
-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:\Python27\Scripts``.
-
-Note that the rest of the documentation assumes this utility is installed
-as ``django-admin``. You'll have to substitute ``django-admin.py`` if you use
-this method.