Update installation instructions and fix formatting

README.rst

@@ -104,30 +104,35 @@ Supports
 Install spaCy
 =============
 
-spaCy is compatible with 64-bit CPython 2.6+/3.3+ and runs on Unix/Linux, OS X 
+spaCy is compatible with **64-bit CPython 2.6+/3.3+** and runs on **Unix/Linux**,
-and Windows. Source packages are available via 
+**macOS/OS X** and **Windows**. The latest spaCy releases are available over
-`pip <https://pypi.python.org/pypi/spacy>`_. Please make sure that
+`pip <https://pypi.python.org/pypi/spacy>`_ (source packages only) and
-you have a working build enviroment set up. See notes on Ubuntu, macOS/OS X and Windows
+`conda <https://anaconda.org/conda-forge/spacy>`_. Installation requires a working
-for details.
+build environment. See notes on Ubuntu, macOS/OS X and Windows for details.
 
 pip
 ---
 
-When using pip it is generally recommended to install packages in a virtualenv to
+Using pip, spaCy releases are currently only available as source packages.
-avoid modifying system state:
 
 .. code:: bash
 
-    pip install spacy
+    pip install -U spacy
 
-Python packaging is awkward at the best of times, and it's particularly tricky with
+When using pip it is generally recommended to install packages in a ``virtualenv``
-C extensions, built via Cython, requiring large data files. So, please report issues
+to avoid modifying system state:
-as you encounter them.
+
+.. code:: bash
+
+    virtualenv .env
+    source .env/bin/activate
+    pip install spacy
 
 conda
 -----
 
-If you're using conda, you can install spaCy via ``conda-forge``:
+Thanks to our great community, we've finally re-added conda support. You can now
+install spaCy via ``conda-forge``:
 
 .. code:: bash
 
@@ -136,14 +141,13 @@ If you're using conda, you can install spaCy via ``conda-forge``:
 
 For the feedstock including the build recipe and configuration,
 check out `this repository <https://github.com/conda-forge/spacy-feedstock>`_.
-Thanks to our great community, we've finally re-added conda support — improvements
+Improvements and pull requests to the recipe and setup are always appreciated.
-and pull requests to the recipe and setup are always appreciated.
 
-Install model
+Download models
-=============
+===============
 
-After installation you need to download a language model. Currently only models for 
+After installation you need to download a language model. Models for English
-English and German, named ``en`` and ``de``, are available.
+(``en``) and German (``de``) are available.
 
 .. code:: bash
 
@@ -153,51 +157,90 @@ English and German, named ``en`` and ``de``, are available.
 The download command fetches about 1 GB of data which it installs
 within the ``spacy`` package directory.
 
-Upgrading spaCy
+Sometimes new releases require a new language model. Then you will have to
-===============
+upgrade to a new model, too. You can also force re-downloading and installing a
-
+new language model:
-To upgrade spaCy to the latest release:
-
-pip
----
-
-.. code:: bash
-
-    pip install -U spacy
-
-Sometimes new releases require a new language model. Then you will have to upgrade to 
-a new model, too. You can also force re-downloading and installing a new language model:
 
 .. code:: bash
 
     python -m spacy.en.download --force
 
+Download model to custom location
+---------------------------------
+
+You can specify where ``spacy.en.download`` and ``spacy.de.download`` download
+the language model to using the ``--data-path`` or ``-d`` argument:
+
+.. code:: bash
+
+    python -m spacy.en.download all --data-path /some/dir
+
+If you choose to download to a custom location, you will need to tell spaCy where to load the model
+from in order to use it. You can do this either by calling ``spacy.util.set_data_path()`` before
+calling ``spacy.load()``, or by passing a ``path`` argument to the ``spacy.en.English`` or
+``spacy.de.German`` constructors.
+
+Download models manually
+------------------------
+
+As of v1.6, the models and word vectors are also available as direct downloads
+from GitHub, attached to the `releases <https://github.com/explosion/spacy/releases>`_
+as ``.tar.gz`` archives.
+
+To install the models manually, first find the default data path. You can use
+``spacy.util.get_data_path()`` to find the directory where spaCy will look for
+its models, or change the default data path with ``spacy.util.set_data_path()``.
+Then simply unpack the archive and place the contained folder in that directory.
+You can now load the models via ``spacy.load()``.
+
 Compile from source
 ===================
 
-The other way to install spaCy is to clone its GitHub repository and build it from 
+The other way to install spaCy is to clone its
+`GitHub repository <https://github.com/explosion/spaCy>`_ and build it from
 source. That is the common way if you want to make changes to the code base.
-
 You'll need to make sure that you have a development enviroment consisting of a
-Python distribution including header files, a compiler, pip, virtualenv and git 
+Python distribution including header files, a compiler,
-installed. The compiler part is the trickiest. How to do that depends on your 
+`pip <https://pip.pypa.io/en/latest/installing/>`__, `virtualenv <https://virtualenv.pypa.io/>`_
-system. See notes on Ubuntu, OS X and Windows for details.
+and `git <https://git-scm.com>`_ installed. The compiler part is the trickiest.
+How to do that depends on your system. See notes on Ubuntu, OS X and Windows for
+details.
 
 .. code:: bash
 
     # make sure you are using recent pip/virtualenv versions
     python -m pip install -U pip virtualenv
-
+    git clone #{gh("spaCy")}
-    #  find git install instructions at https://git-scm.com/downloads
-    git clone https://github.com/explosion/spaCy.git
-
     cd spaCy
-    virtualenv .env && source .env/bin/activate
+
+    virtualenv .env
+    source .env/bin/activate
     pip install -r requirements.txt
     pip install -e .
 
 Compared to regular install via pip `requirements.txt <requirements.txt>`_
-additionally installs developer dependencies such as cython.
+additionally installs developer dependencies such as Cython.
+
+Instead of the above verbose commands, you can also use the following
+`Fabric <http://www.fabfile.org/>`_ commands:
+
++---------------+--------------------------------------------------------------+
+| ``fab env``   | Create ``virtualenv`` and delete previous one, if it exists. |
++---------------+--------------------------------------------------------------+
+| ``fab make``  | Compile the source.                                          |
++---------------+--------------------------------------------------------------+
+| ``fab clean`` | Remove compiled objects, including the generated C++.        |
++---------------+--------------------------------------------------------------+
+| ``fab test``  | Run basic tests, aborting after first failure.               |
++---------------+--------------------------------------------------------------+
+
+All commands assume that your ``virtualenv`` is located in a directory ``.env``.
+If you're using a different directory, you can change it via the environment
+variable ``VENV_DIR``, for example:
+
+.. code:: bash
+
+    VENV_DIR=".custom-env" fab clean make
 
 Ubuntu
 ------
@@ -226,8 +269,8 @@ VS 2010 (Python 3.4) and VS 2015 (Python 3.5).
 Run tests
 =========
 
-spaCy comes with an extensive test suite. First, find out where spaCy is 
+spaCy comes with an `extensive test suite <spacy/tests>`_. First, find out where
-installed:
+spaCy is installed:
 
 .. code:: bash
 
@@ -243,22 +286,6 @@ and ``--model`` are optional and enable additional tests:
 
     python -m pytest <spacy-directory> --vectors --model --slow
 
-Download model to custom location
-=================================
-
-You can specify where ``spacy.en.download`` and ``spacy.de.download`` download the language model
-to using the ``--data-path`` or ``-d`` argument:
-
-.. code:: bash
-    
-    python -m spacy.en.download all --data-path /some/dir
-
-
-If you choose to download to a custom location, you will need to tell spaCy where to load the model
-from in order to use it. You can do this either by calling ``spacy.util.set_data_path()`` before
-calling ``spacy.load()``, or by passing a ``path`` argument to the ``spacy.en.English`` or
-``spacy.de.German`` constructors.
-
 Changelog
 =========
 

website/docs/usage/index.jade

@@ -66,7 +66,9 @@ p
     # Check whether the model was successfully installed
     python -c "import spacy; spacy.load('en'); print('OK')"
 
-p The download command fetches about 1 GB of data which it installs within the #[code spacy] package directory.
+p
+    |  The download command fetches about 1 GB of data which it
+    |  installs within the #[code spacy] package directory.
 
 +h(3, "custom-location") Download model to custom location
 
@@ -144,7 +146,7 @@ p
 
     +row
         +cell #[code fab clean]
-        +cell Remove compiled objects including the generated C++.
+        +cell Remove compiled objects, including the generated C++.
 
     +row
         +cell #[code fab test]
@@ -153,7 +155,7 @@ p
 p
     |  All commands assume that your #[code virtualenv] is located in a
     |  directory #[code .env]. If you're using a different directory, you can
-    |  change it via environment the variable #[code VENV_DIR], for example:
+    |  change it via the environment variable #[code VENV_DIR], for example:
 
 +code(false, "bash").
     VENV_DIR=".custom-env" fab clean make