DOC: Add docs section on installation.

README.rst

@@ -12,17 +12,19 @@ Zipline is a Pythonic algorithmic trading library. It is an event-driven
 system that supports both backtesting and live-trading.
 
 Zipline is currently used in production as the backtesting and live-trading
-engine powering `Quantopian <https://www.quantopian.com>`__ -- a free,
+engine powering `Quantopian <https://www.quantopian.com>`_ -- a free,
 community-centered, hosted platform for building and executing trading
 strategies.
 
 `Join our
-community! <https://groups.google.com/forum/#!forum/zipline>`__
+community! <https://groups.google.com/forum/#!forum/zipline>`_
+
+`Documentation <http://www.zipline.io>`_
 
 Want to contribute? See our `open
-requests <https://github.com/quantopian/zipline/wiki/Contribution-Requests>`__
+requests <https://github.com/quantopian/zipline/wiki/Contribution-Requests>`_
 and our `general
-guidelines <https://github.com/quantopian/zipline#contributions>`__
+guidelines <https://github.com/quantopian/zipline#contributions>`_
 below.
 
 Features
@@ -43,25 +45,49 @@ Features
 Installation
 ============
 
-pip
----
+Installing With ``pip``
+-----------------------
+
+Assuming you have all required (see note below) non-Python dependencies, you
+can install Zipline with ``pip`` via:
 
-You can install Zipline via the ``pip`` command:
-::
+.. code-block:: bash
 
     $ pip install zipline
 
+**Note:** Installing Zipline via ``pip`` is slightly more involved than the
+average Python package.  Simply running ``pip install zipline`` will likely
+fail if you've never installed any scientific Python packages before.
+
+There are two reasons for the additional complexity:
+
+1. Zipline ships several C extensions that require access to the CPython C API.
+   In order to build the C extensions, ``pip`` needs access to the CPython
+   header files for your Python installation.
+
+2. Zipline depends on `numpy <http://www.numpy.org/>`_, the core library for
+   numerical array computing in Python.  Numpy depends on having the `LAPACK
+   <http://www.netlib.org/lapack>`_ linear algebra routines available.
+
+Because LAPACK and the CPython headers are binary dependencies, the correct way
+to install them varies from platform to platform.  On Linux, users generally
+acquire these dependencies via a package manager like ``apt``, ``yum``, or
+``pacman``.  On OSX, `Homebrew <http://www.brew.sh>`_ is a popular choice
+providing similar functionality.
+
+See the full `Zipline Install Documentation`_ for more information on acquiring
+binary dependencies for your specific platform.
 
 conda
 -----
 
-Another way to install Zipline is via ``conda`` which comes as part
-of `Anaconda <http://continuum.io/downloads>`__ or can be installed via
-``pip install conda``.
+Another way to install Zipline is via the ``conda`` package manager, which
+comes as part of `Anaconda <http://continuum.io/downloads>`_ or can be
+installed via ``pip install conda``.
 
 Once set up, you can install Zipline from our ``Quantopian`` channel:
 
-::
+.. code-block:: bash
 
     conda install -c Quantopian zipline
 
@@ -74,17 +100,11 @@ Currently supported platforms include:
 
    Windows may work; however, it is currently untested.
 
-Dependencies
-------------
-
-See our `requirements file
-<https://github.com/quantopian/zipline/blob/master/etc/requirements.txt>`__
-
 Quickstart
 ==========
 
 See our `getting started
-tutorial <http://www.zipline.io/#quickstart>`__.
+tutorial <http://www.zipline.io/#quickstart>`_.
 
 The following code implements a simple dual moving average algorithm.
 
@@ -166,3 +186,5 @@ https://github.com/quantopian/zipline/wiki/Contribution-Requests
    :target: https://coveralls.io/r/quantopian/zipline
 .. |Code quality| image:: https://scrutinizer-ci.com/g/quantopian/zipline/badges/quality-score.png?b=master
    :target: https://scrutinizer-ci.com/g/quantopian/zipline/
+
+.. _`Zipline Install Documentation` : http://www.zipline.io/install.html

docs/source/conf.py

@@ -16,6 +16,7 @@
     'sphinx.ext.extlinks',
     'sphinx.ext.autosummary',
     'sphinx.ext.viewcode',
+    'sphinx.ext.todo',
 ]
 
 
@@ -90,3 +91,5 @@
 }
 
 doctest_global_setup = "import zipline"
+
+todo_include_todos = True

docs/source/index.rst

@@ -1,11 +1,9 @@
 .. include:: ../../README.rst
 
-Index
------
-
 .. toctree::
    :maxdepth: 1
 
+   install
    beginner-tutorial
    releases
    appendix

docs/source/install.rst

@@ -0,0 +1,130 @@
+Install
+=======
+
+Installing with ``pip``
+-----------------------
+
+Installing Zipline via ``pip`` is slightly more involved than the average
+Python package.
+
+There are two reasons for the additional complexity:
+
+1. Zipline ships several C extensions that require access to the CPython C API.
+   In order to build the C extensions, ``pip`` needs access to the CPython
+   header files for your Python installation.
+
+2. Zipline depends on `numpy <http://www.numpy.org/>`_, the core library for
+   numerical array computing in Python.  Numpy depends on having the `LAPACK
+   <http://www.netlib.org/lapack>`_ linear algebra routines available.
+
+Because LAPACK and the CPython headers are non-Python dependencies, the correct
+way to install them varies from platform to platform.  If you'd rather use a
+single tool to install Python and non-Python dependencies, or if you're already
+using `Anaconda <http://continuum.io/downloads>`_ as your Python distribution,
+you can skip to the :ref:`Installing with Conda <conda>` section.
+
+Once you've installed the necessary additional depdendencies (see below for
+your particular platform), you should be able to simply run
+
+.. code-block:: bash
+
+   $ pip install zipline
+
+If you use Python for anything other than Zipline, we **strongly** recommend
+that you install in a `virtualenv
+<https://virtualenv.readthedocs.org/en/latest>`_.  The `Hitchhiker's Guide to
+Python`_ provides an `excellent tutorial on virtualenv
+<http://docs.python-guide.org/en/latest/dev/virtualenvs/>`_.
+
+GNU/Linux
+~~~~~~~~~
+
+On `Debian-derived`_ Linux distributions, you can acquire all the necessary
+binary dependencies from ``apt`` by running:
+
+.. code-block:: bash
+
+   $ sudo apt-get install libatlas-base-dev python-dev gfortran pkg-config
+
+On recent `RHEL-derived`_ derived Linux distributions (e.g. Fedora), the
+following should be sufficient to acquire the necessary additional
+dependencies:
+
+.. code-block:: bash
+
+   $ sudo dnf install atlas-devel gcc-c++ gcc-gfortran libgfortran python-devel redhat-rep-config
+
+On `Arch Linux`_, you can acquire the additional dependencies via ``pacman``:
+
+.. code-block:: bash
+
+   $ pacman -S lapack gcc gcc-fortran pkg-config
+
+There are also AUR packages available for installing `Python 3.4
+<https://aur.archlinux.org/packages/python34/>`_ (Arch's default python is now
+3.5, but Zipline only currently supports 3.4), and `ta-lib
+<https://aur.archlinux.org/packages/ta-lib/>`_, an optional Zipline dependency.
+Python 2 is also installable via:
+
+.. code-block:: bash
+
+   $ pacman -S python2
+
+OSX
+~~~
+
+The version of Python shipped with OSX by default is generally out of date, and
+has a number of quirks because it's used directly by the operating system.  For
+these reasons, many developers choose to install and use a separate Python
+installation. The `Hitchhiker's Guide to Python`_ provides an excellent guide
+to `Installing Python on OSX <http://docs.python-guide.org/en/latest/>`_, which
+explains how to install Python with the [Homebrew](http://brew.sh/) package
+manager.
+
+Assuming you've installed Python with Homebrew, you'll also likely need the
+following brew packages:
+
+.. code-block:: bash
+
+   $ brew install freetype pkg-config gcc openssl
+
+Windows
+~~~~~~~
+
+.. todo::
+
+   Add notes on installing with Anaconda, then point to ``Installing with Conda``.
+
+Installing with ``conda``
+-------------------------
+.. _conda:
+
+.. warning::
+
+   The ``zipline`` packages for ``conda`` are currently out of date.  We plan
+   to provide a conda package for the upcoming ``0.8.4`` release.
+
+Another way to install Zipline is via the ``conda`` package manager, which
+comes as part of Continuum Analytics' `Anaconda
+<http://continuum.io/downloads>`_ distribution.
+
+The primary advantage of using Conda over ``pip`` is that conda natively
+understands the complex binary dependencies of packages like ``numpy`` and
+``scipy``.  This means that ``conda`` can install Zipline and its dependencies
+without requiring the use of a second tool to acquire Zipline's non-Python
+dependencies.
+
+For instructions on how to install ``conda``, see the `Conda Installation
+Documentation <http://conda.pydata.org/docs/download.html>`_
+
+Once conda has been set up you can install Zipline from our ``Quantopian``
+channel:
+
+.. code-block:: bash
+
+    conda install -c Quantopian zipline
+
+.. _`Debian-derived`: https://www.debian.org/misc/children-distros
+.. _`RHEL-derived`: https://en.wikipedia.org/wiki/Red_Hat_Enterprise_Linux_derivatives
+.. _`Arch Linux` : https://www.archlinux.org/
+.. _`Hitchhiker's Guide to Python` : http://docs.python-guide.org/en/latest/

etc/requirements_docs.txt

@@ -0,0 +1,2 @@
+Sphinx>=1.3.2
+numpydoc>=0.5.0