First stab at Python3 OS X docs

Author: Adam Nelson

docs/dev/virtualenvs.rst

@@ -8,15 +8,22 @@ projects in separate places, by creating virtual Python environments for them.
 It solves the "Project X depends on version 1.x but, Project Y needs 4.x"
 dilemma, and keeps your global site-packages directory clean and manageable.
 
-For example, you can work on a project which requires Django 1.3 while also
-maintaining a project which requires Django 1.0.
+For example, you can work on a project which requires Django 1.9 while also
+maintaining a project which requires Django 1.8.
+
+If you are using Python 3, make sure you run something like the following (or
+have it in your env variables in `~/.bashrc`):
+
+.. code-block:: console
+
+    $ export VIRTUALENVWRAPPER_PYTHON=/usr/local/bin/python3
 
 virtualenv
 ----------
 
 `virtualenv <http://pypi.python.org/pypi/virtualenv>`_ is a tool to create
-isolated Python environments. virtualenv creates a folder which contains all the 
-necessary executables to use the packages that a Python project would need. 
+isolated Python environments. virtualenv creates a folder which contains all the
+necessary executables to use the packages that a Python project would need.
 
 Install virtualenv via pip:
 
@@ -43,23 +50,23 @@ in the current directory instead.
 This creates a copy of Python in whichever directory you ran the command in,
 placing it in a folder named :file:`venv`.
 
-You can also use a Python interpreter of your choice.
+You can also use the Python interpreter of your choice.
 
 .. code-block:: console
 
-   $ virtualenv -p /usr/bin/python2.7 venv
+   $ virtualenv -p /usr/local/bin/python3 venv
 
-This will use the Python interpreter in :file:`/usr/bin/python2.7`
+This will use the Python interpreter in :file:`/usr/local/bin/python3`
 
 2. To begin using the virtual environment, it needs to be activated:
 
 .. code-block:: console
 
    $ source venv/bin/activate
 
-The name of the current virtual environment will now appear on the left of 
-the prompt (e.g. ``(venv)Your-Computer:your_project UserName$)`` to let you know 
-that it's active. From now on, any package that you install using pip will be 
+The name of the current virtual environment will now appear on the left of
+the prompt (e.g. ``(venv)Your-Computer:your_project UserName$)`` to let you know
+that it's active. From now on, any package that you install using pip will be
 placed in the ``venv`` folder, isolated from the global Python installation.
 
 Install packages as usual, for example:
@@ -78,7 +85,7 @@ Install packages as usual, for example:
 This puts you back to the system's default Python interpreter with all its
 installed libraries.
 
-To delete a virtual environment, just delete its folder. (In this case, 
+To delete a virtual environment, just delete its folder. (In this case,
 it would be ``rm -rf venv``.)
 
 After a while, though, you might end up with a lot of virtual environments
@@ -102,8 +109,8 @@ the current state of the environment packages. To do this, run
 
 This will create a :file:`requirements.txt` file, which contains a simple
 list of all the packages in the current environment, and their respective
-versions. You can see the list of installed packages without the requirements 
-format using "pip list". Later it will be easier for a different developer 
+versions. You can see the list of installed packages without the requirements
+format using "pip list". Later it will be easier for a different developer
 (or you, if you need to re-create the environment) to install the same packages
 using the same versions:
 
@@ -143,7 +150,7 @@ To install (make sure **virtualenv** is already installed):
 .. code-block:: console
 
   $ pip install virtualenvwrapper-win
-  
+
 In Windows, the default path for WORKON_HOME is %USERPROFILE%\Envs
 
 Basic Usage

docs/starting/install/osx.rst

@@ -3,6 +3,9 @@
 Installing Python on Mac OS X
 =============================
 
+.. note::
+    Check out our :ref:`guide for installing Python 3 on OS X<install3-osx>`.
+
 The latest version of Mac OS X, El Capitan, **comes with Python 2.7 out of the box**.
 
 You do not need to install or configure anything else to use Python. Having said

docs/starting/install3/osx.rst

@@ -0,0 +1,116 @@
+.. _install3-osx:
+
+Installing Python 3 on Mac OS X
+================================
+
+The latest version of Mac OS X, El Capitan, **comes with Python 2.7 out of the box**.
+
+You do not need to install or configure anything else to use Python 2. These
+instructions document the installation of Python 3.
+
+The version of Python that ships with OS X is great for learning but it's not
+good for development. The version shipped with OS X may be out of date from the
+`official current Python release <https://www.python.org/downloads/mac-osx/>`_,
+which is considered the stable production version.
+
+Doing it Right
+--------------
+
+Let's install a real version of Python.
+
+Before installing Python, you'll need to install GCC. GCC can be obtained
+by downloading `XCode <http://developer.apple.com/xcode/>`_, the smaller
+`Command Line Tools <https://developer.apple.com/downloads/>`_ (must have an
+Apple account) or the even smaller `OSX-GCC-Installer <https://github.com/kennethreitz/osx-gcc-installer#readme>`_
+package.
+
+.. note::
+    If you already have XCode installed, do not install OSX-GCC-Installer.
+    In combination, the software can cause issues that are difficult to
+    diagnose.
+
+.. note::
+    If you perform a fresh install of XCode, you will also need to add the
+    commandline tools by running ``xcode-select --install`` on the terminal.
+
+While OS X comes with a large number of UNIX utilities, those familiar with
+Linux systems will notice one key component missing: a package manager.
+`Homebrew <http://brew.sh>`_ fills this void.
+
+To `install Homebrew <http://brew.sh/#install>`_, open :file:`Terminal` or
+your favorite OSX terminal emulator and run
+
+.. code-block:: console
+
+    $ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
+
+The script will explain what changes it will make and prompt you before the
+installation begins.
+Once you've installed Homebrew, insert the Homebrew directory at the top
+of your :envvar:`PATH` environment variable. You can do this by adding the following
+line at the bottom of your :file:`~/.profile` file
+
+.. code-block:: console
+
+    export PATH=/usr/local/bin:/usr/local/sbin:$PATH
+
+Now, we can install Python 3:
+
+.. code-block:: console
+
+    $ brew install python3
+
+This will take a minute or two.
+
+
+Pip
+----------------
+
+Homebrew installs ``pip3`` for you.
+
+``pip3`` is the alias for the Python 3 version of ``pip`` on systems with both
+the Homebrew'd Python 2 and 3 installed.
+
+Working with Python3
+--------------------
+
+At this point, you have the system Python 2.7 available, potentially the
+:ref:`Homebrew version of Python 2 <install-osx>` installed, and the Homebrew
+version of Python 3 as well.
+
+.. code-block:: console
+
+    $ python
+
+will launch the Python 2 interpreter.
+
+.. code-block:: console
+
+    $ python3
+
+will launch the Python 3 interpreter
+
+``pip3`` and ``pip`` will both be available.  If the Homebrew version of Python
+2 is not installed, they will be the same.  If the Homebrew version of Python 2
+is installed then ``pip`` will point to Python 2 and ``pip3`` will point to
+Python 3.
+
+
+Virtual Environments
+--------------------
+
+A Virtual Environment (commonly referred to as a 'virtualenv') is a tool to keep
+the dependencies required by different projects in separate places, by creating
+virtual Python environments for them. It solves the "Project X depends on
+version 1.x but, Project Y needs 4.x" dilemma, and keeps your global
+site-packages directory clean and manageable.
+
+For example, you can work on a project which requires Django 1.10 while also
+maintaining a project which requires Django 1.8.
+
+To start using this and see more information: :ref:`Virtual Environments <virtualenvironments-ref>` docs.
+
+--------------------------------
+
+This page is a remixed version of `another guide <http://www.stuartellis.eu/articles/python-development-windows/>`_,
+which is available under the same license.

docs/starting/installation.rst

@@ -13,9 +13,11 @@ other third-party Python libraries.
 Installation Guides
 -------------------
 
-These guides go over the proper installation of :ref:`Python 2.7 <which-python>`
+These guides go over the proper installation of :ref:`Python <which-python>`
 for development purposes, as well as pip and virtualenv.
 
-- :ref:`Mac OS X <install-osx>`.
-- :ref:`Microsoft Windows <install-windows>`.
-- :ref:`Ubuntu Linux <install-linux>`.
+- :ref:`Python 3 on Mac OS X <install3-osx>`.
+
+- :ref:`Python 2 on Mac OS X <install-osx>`.
+- :ref:`Python 2 on Microsoft Windows <install-windows>`.
+- :ref:`Python 2 on Ubuntu Linux <install-linux>`.