diff --git a/README.rst b/README.rst index d2e15993..4c324f8e 100644 --- a/README.rst +++ b/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 `__ -- a free, +engine powering `Quantopian `_ -- a free, community-centered, hosted platform for building and executing trading strategies. `Join our -community! `__ +community! `_ + +`Documentation `_ Want to contribute? See our `open -requests `__ +requests `_ and our `general -guidelines `__ +guidelines `_ below. Features @@ -43,25 +45,49 @@ Features Installation ============ -pip ---- +Installing With ``pip`` +----------------------- -You can install Zipline via the ``pip`` command: -:: +Assuming you have all required (see note below) non-Python dependencies, you +can install Zipline with ``pip`` via: + +.. 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 `_, the core library for + numerical array computing in Python. Numpy depends on having the `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 `_ 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 `__ 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 `_ 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 -`__ - Quickstart ========== See our `getting started -tutorial `__. +tutorial `_. 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 diff --git a/docs/source/conf.py b/docs/source/conf.py index 06dae84c..d8f8600d 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -16,6 +16,7 @@ extensions = [ 'sphinx.ext.extlinks', 'sphinx.ext.autosummary', 'sphinx.ext.viewcode', + 'sphinx.ext.todo', ] @@ -90,3 +91,5 @@ intersphinx_mapping = { } doctest_global_setup = "import zipline" + +todo_include_todos = True diff --git a/docs/source/index.rst b/docs/source/index.rst index 29b94bb8..9dad6958 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,11 +1,9 @@ .. include:: ../../README.rst -Index ------ - .. toctree:: :maxdepth: 1 + install beginner-tutorial releases appendix diff --git a/docs/source/install.rst b/docs/source/install.rst new file mode 100644 index 00000000..4e05e01f --- /dev/null +++ b/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 `_, the core library for + numerical array computing in Python. Numpy depends on having the `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 `_ as your Python distribution, +you can skip to the :ref:`Installing with 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 +`_. The `Hitchhiker's Guide to +Python`_ provides an `excellent tutorial on virtualenv +`_. + +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 +`_ (Arch's default python is now +3.5, but Zipline only currently supports 3.4), and `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 `_, 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 +`_ 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 `_ + +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/ diff --git a/docs/source/whatsnew/0.8.4.txt b/docs/source/whatsnew/0.8.4.txt index a55df6fe..b5942387 100644 --- a/docs/source/whatsnew/0.8.4.txt +++ b/docs/source/whatsnew/0.8.4.txt @@ -83,6 +83,8 @@ Documentation * Added reference docs for Asset Metadata APIs. (:issue:`864`). * Generated documentation now includes links to source code for many classes and functions. (:issue:`864`). +* Added platform-specific documentation describing how to find binary + dependencies. (:issue:`883`). Miscellaneous ~~~~~~~~~~~~~ diff --git a/etc/requirements_docs.txt b/etc/requirements_docs.txt new file mode 100644 index 00000000..8dc2d5c1 --- /dev/null +++ b/etc/requirements_docs.txt @@ -0,0 +1,2 @@ +Sphinx>=1.3.2 +numpydoc>=0.5.0