Update windows install instructions (#2039)

* Update readme

* Note that running tests locally requires installing in editable mode

* Update corresponding section in installation notes

* clarify note about --no-use-pep517

CONTRIBUTING.rst

@@ -217,6 +217,8 @@ package layout.
 
 To run the entire suite and the code coverage report:
 
+Note: rasterio must be installed in editable mode in order to run tests.
+
 .. code-block:: console
 
     $ py.test --cov rasterio --cov-report term-missing

README.rst

@@ -299,12 +299,25 @@ cannot rely on gdal-config, which is only present on UNIX systems, to discover
 the locations of header files and libraries that rasterio needs to compile its
 C extensions. On Windows, these paths need to be provided by the user. You
 will need to find the include files and the library files for gdal and use
-setup.py as follows.
+setup.py as follows. You will also need to specify the installed gdal version
+through the GDAL_VERSION environment variable.
 
 .. code-block:: console
 
-    $ python setup.py build_ext -I<path to gdal include files> -lgdal_i -L<path to gdal library>
-    $ python setup.py install
+    $ python setup.py build_ext -I<path to gdal include files> -lgdal_i -L<path to gdal library> install
+
+With pip
+
+.. code-block:: console
+
+    $ pip install --no-use-pep517 --global-option -I<path to gdal include files> -lgdal_i -L<path to gdal library> .
+
+Note: :code:`--no-use-pep517` is required as pip currently hasn't implemented a
+way for optional arguments to be passed to the build backend when using PEP 517. 
+See  `here <https://github.com/pypa/pip/issues/5771>`__. for more details.
+
+Alternatively environment variables (e.g. INCLUDE and LINK) used by MSVC compiler can be used to point 
+to include directories and library files.
 
 We have had success compiling code using the same version of Microsoft's
 Visual Studio used to compile the targeted version of Python (more info on

docs/installation.rst

@@ -109,8 +109,20 @@ setup.py as follows.
 
 .. code-block:: console
 
-    $ python setup.py build_ext -I<path to gdal include files> -lgdal_i -L<path to gdal library>
-    $ python setup.py install
+    $ python setup.py build_ext -I<path to gdal include files> -lgdal_i -L<path to gdal library> install
+
+With pip
+
+.. code-block:: console
+
+    $ pip install --no-use-pep517 --global-option -I<path to gdal include files> -lgdal_i -L<path to gdal library> .
+
+Note: :code:`--no-use-pep517` is required as pip currently hasn't implemented a
+way for optional arguments to be passed to the build backend when using PEP 517. 
+See  `here <https://github.com/pypa/pip/issues/5771>`__. for more details.
+
+Alternatively environment variables (e.g. INCLUDE and LINK) used by MSVC compiler can be used to point 
+to include directories and library files.
 
 We have had success compiling code using the same version of Microsoft's
 Visual Studio used to compile the targeted version of Python (more info on