Merge pull request #673 from mapbox/doc-polish

[NOT READY] Documentation polish

README.rst

@@ -19,8 +19,8 @@ Rasterio is pronounced raw-STEER-ee-oh.
 Example
 =======
 
-Here's a simple example of the basic features rasterio provides. Three bands
-are read from an image and summed to produce something like a panchromatic
+Here's an example of some basic features that rasterio provides. Three bands
+are read from an image and averaged to produce something like a panchromatic
 band.  This new band is then written to a new single band TIFF.
 
 .. code-block:: python
@@ -62,7 +62,7 @@ The output:
 API Overview
 ============
 
-Simple access is provided to properties of a geospatial raster file.
+Rasterio gives access to properties of a geospatial raster file.
 
 .. code-block:: python
 
@@ -81,7 +81,7 @@ Simple access is provided to properties of a geospatial raster file.
     # 3
     # [1, 2, 3]
 
-A dataset also provides methods for getting extended array slices given
+A rasterio dataset also provides methods for getting extended array slices given
 georeferenced coordinates and vice versa.
 
 
@@ -140,7 +140,7 @@ using Python.
 Rio Plugins
 -----------
 
-Rio provides the ability to create additional subcommands using plugins.  See
+Rio provides the ability to create subcommands using plugins.  See
 `cli.rst <https://github.com/mapbox/rasterio/blob/master/docs/cli.rst#rio-plugins>`__
 for more information on building plugins.
 
@@ -171,7 +171,7 @@ OS X
 ----
 
 Binary wheels with the GDAL, GEOS, and PROJ4 libraries included are available
-for OS X versions 10.7+ starting with Rasterio version 0.17. To install, just
+for OS X versions 10.7+ starting with Rasterio version 0.17. To install,
 run ``pip install rasterio``. These binary wheels are preferred by newer
 versions of pip. If you don't want these wheels and want to install from
 a source distribution, run ``pip install rasterio --no-use-wheel`` instead.

docs/cli.rst

@@ -535,8 +535,8 @@ The ``stack`` command stacks a number of bands from one or more input files
 into a multiband dataset. Input datasets must be of a kind: same data type,
 dimensions, etc. The output is cloned from the first input. By default,
 ``stack`` will take all bands from each input and write them in same order to
-the output. Optionally, bands for each input may be specified using a simple
-syntax:
+the output. Optionally, bands for each input may be specified using the
+following syntax:
 
 - ``--bidx N`` takes the Nth band from the input (first band is 1).
 - ``--bidx M,N,O`` takes bands M, N, and O.
@@ -642,7 +642,7 @@ a command ``rio mbtiles`` to export a raster to an MBTiles file.
 See `click-plugins <https://github.com/click-contrib/click-plugins>`__ for more
 information on how to build these plugins in general.
 
-In order to use these plugins with rio, add the commands to the
+To use these plugins with rio, add the commands to the
 ``rasterio.rio_plugins'`` entry point in your ``setup.py`` file, as described
 `here <https://github.com/click-contrib/click-plugins#developing-plugins>`__
 

docs/cookbook.rst

@@ -115,7 +115,7 @@ Creating a least cost path
 Using a scipy filter to smooth a raster
 ---------------------------------------
 
-This recipe demonstrates the use of scipy's `signal processing filters <http://docs.scipy.org/doc/scipy/reference/signal.html#signal-processing-scipy-signal>`_ to manipulate multi-band raster imagery
+This recipe demonstrates scipy's `signal processing filters <http://docs.scipy.org/doc/scipy/reference/signal.html#signal-processing-scipy-signal>`_ to manipulate multi-band raster imagery
 and save the results to a new GeoTIFF. Here we apply a median filter to smooth
 the image and remove small inclusions (at the expense of some sharpness and detail).
 
@@ -141,7 +141,7 @@ With median filter applied
 Using skimage to adjust the saturation of a RGB raster
 ------------------------------------------------------
 
-This recipe demonstrates the use of manipulating color with the scikit image `color module <http://scikit-image.org/docs/stable/api/skimage.color.html>`_.
+This recipe demonstrates manipulating color with the scikit image `color module <http://scikit-image.org/docs/stable/api/skimage.color.html>`_.
 
 .. literalinclude:: recipes/saturation.py
     :language: python

docs/features.rst

@@ -4,7 +4,7 @@ Vector Features
 Rasterio's ``features`` module provides functions to extract shapes of raster
 features and to create new features by "burning" shapes into rasters:
 ``shapes()`` and ``rasterize()``. These functions expose GDAL functions in
-a very general way, using iterators over GeoJSON-like Python objects instead of
+a general way, using iterators over GeoJSON-like Python objects instead of
 GIS layers.
 
 Extracting shapes of raster features
@@ -65,7 +65,7 @@ By default, only pixels whose center is within the polygon or that
 are selected by Bresenham's line algorithm will be burned in.  
 You can specify ``all_touched=True`` to burn in all pixels touched by the geometry.
 The geometries will be rasterized by the "painter's algorithm" - 
-geometries are handled in order and subsequent geometries will overwrite previous values.
+geometries are handled in order and later geometries will overwrite earlier values.
 
 Again, to burn in georeferenced shapes, pass an appropriate transform for the
 image to be created.

docs/georeferencing.rst

@@ -61,10 +61,10 @@ a pixel's image coordinates are ``x, y`` and its world coordinates are
     | y' | = | d e f | | y |
     | 1  |   | 0 0 1 | | 1 |
 
-The ``Affine`` class has a number of useful properties and methods
+The ``Affine`` class has some useful properties and methods
 described at https://github.com/sgillies/affine.
 
-Previous versions of Rasterio had a ``transform`` attribute which was a 6-element
+Earlier versions of Rasterio had a ``transform`` attribute which was a 6-element
 tuple. This usage is deprecated, please see https://github.com/mapbox/rasterio/issues/86 for details. 
 In Rasterio 1.0, the value of a  ``transform`` attribute will be an instance
 of ``Affine`` and the ``affine`` attribute will remain as an alias.

docs/installation.rst

@@ -4,8 +4,8 @@ Installation
 Dependencies
 ************************
 
-Rasterio has one C library dependency: ``GDAL >=1.9``. GDAL itself depends on a
-number of other libraries provided by most major operating systems and also
+Rasterio has one C library dependency: ``GDAL >=1.9``. GDAL itself depends on
+many of other libraries provided by most major operating systems and also
 depends on the non standard GEOS and PROJ4 libraries.
 
 Python package dependencies (see also requirements.txt): ``affine, cligj, click, enum34, numpy``.
@@ -19,7 +19,7 @@ OS X
 ----
 
 Binary wheels with the GDAL, GEOS, and PROJ4 libraries included are available
-for OS X versions 10.7+ starting with Rasterio version 0.17. To install, just
+for OS X versions 10.7+ starting with Rasterio version 0.17. To install, 
 run ``pip install rasterio``. These binary wheels are preferred by newer
 versions of pip. If you don't want these wheels and want to install from
 a source distribution, run ``pip install rasterio --no-use-wheel`` instead.
@@ -37,7 +37,7 @@ Windows
 Binary wheels for rasterio and GDAL are created by Christoph Gohlke and are
 available from his website.
 
-To install rasterio, simply download both binaries for your system (`rasterio
+To install rasterio, download both binaries for your system (`rasterio
 <http://www.lfd.uci.edu/~gohlke/pythonlibs/#rasterio>`__ and `GDAL
 <http://www.lfd.uci.edu/~gohlke/pythonlibs/#gdal>`__) and run something like
 this from the downloads folder:

docs/masks.rst

@@ -17,7 +17,7 @@ trapezoid of image data within a rectangular background of 0,0,0 value pixels.
 
 .. image:: https://www.dropbox.com/s/sg7qejccih5m4ah/RGB.byte.jpg?dl=1
 
-Metadata in the dataset declares that values of 0 shall be interpreted as
+Metadata in the dataset declares that values of 0 will be interpreted as
 invalid data or *nodata* pixels. In, e.g., merging the image with adjacent
 scenes, we'd like to ignore the nodata pixels and have only valid image data in
 our final mosaic.
@@ -82,7 +82,7 @@ a problem inherent in 8-bit raster data: lack of dynamic range. The dataset
 creator has said that 0 values represent missing data (see the
 ``nodatavals`` property in the first code block of this document), but some of
 the valid data have values so low they've been rounded during processing to
-zero.  This can very easily happen in scaling 16-bit data to 8 bits.  There's
+zero.  This can happen in scaling 16-bit data to 8 bits.  There's
 no magic nodata value bullet for this. Using 16 bits per band helps, but you
 really have to be careful with 8-bit per band datasets and their nodata values.
 
@@ -196,7 +196,7 @@ If you want, you can read dataset bands as numpy masked arrays.
            [ True,  True,  True, ...,  True,  True,  True]], dtype=bool)
 
 As mentioned earlier, this mask is the inverse of the GDAL band mask. To get
-a mask conforming to GDAL RFC 15, simply do this:
+a mask conforming to GDAL RFC 15, do this:
 
 .. code-block:: python
 

docs/osgeo_gdal_migration.rst

@@ -10,7 +10,7 @@ This section will discuss the differences between ``rasterio`` and ``osgeo.gdal`
 choose to use one over the other.
 
 ``osgeo.gdal`` is automatically-generated using swig. As a result, the interface and method names are
-very similar to the native C++ API.  The ``rasterio`` library is built with Cython which allows
+similar to the native C++ API.  The ``rasterio`` library is built with Cython which allows
 us to create an interface that follows the style and conventions of familiar Python code.
 
 This is best illustrated by example.  Opening a raster file with ``osgeo.gdal`` involves using gdal constants and the programmer must provide their own error handling and memory management ::

docs/reading.rst

@@ -34,7 +34,7 @@ objects.
     >>> src.closed
     False
 
-If you attempt to access a nonexistent path, ``rasterio.open()`` does the same
+If you try to access a nonexistent path, ``rasterio.open()`` does the same
 thing as ``open()``, raising an exception immediately.
 
 .. code-block:: python
@@ -59,7 +59,7 @@ a file can be read like this:
     (718, 791)
 
 The returned object is a 2-dimensional Numpy ndarray. The representation of
-that array at the Python prompt is just a summary; the GeoTIFF file that
+that array at the Python prompt is a summary; the GeoTIFF file that
 Rasterio uses for testing has 0 values in the corners, but has nonzero values
 elsewhere.
 

docs/reproject.rst

@@ -8,7 +8,7 @@ coordinate reference system and transform to the pixels of a source image with
 a different coordinate reference system and transform. This process is known as
 reprojection.
 
-Rasterio's ``rasterio.warp.reproject()`` is a very geospatial-specific analog
+Rasterio's ``rasterio.warp.reproject()`` is a geospatial-specific analog
 to SciPy's ``scipy.ndimage.interpolation.geometric_transform()`` [1]_.
 
 The code below reprojects between two arrays, using no pre-existing GIS
@@ -58,7 +58,7 @@ transform.
 
 See `examples/reproject.py <https://github.com/mapbox/rasterio/blob/master/examples/reproject.py>`__
 for code that writes the destination array to a GeoTIFF file. I've uploaded the
-resulting file to a Mapbox map to demonstrate that the reprojection is
+resulting file to a Mapbox map to show that the reprojection is
 correct: https://a.tiles.mapbox.com/v3/sgillies.hfek2oko/page.html?secure=1#6/0.000/0.033.
 
 Reprojecting a GeoTIFF dataset

docs/tags.rst

@@ -19,7 +19,7 @@ I'm going to use the rasterio interactive inspector in these examples below.
     >>> 
 
 Tags belong to namespaces. To get a copy of a dataset's tags from the default
-namespace, just call ``tags()`` with no arguments.
+namespace, call ``tags()`` with no arguments.
 
 .. code-block:: pycon
 

docs/windowed-rw.rst

@@ -2,8 +2,8 @@ Windowed reading and writing
 ****************************
 
 Beginning in rasterio 0.3, you can read and write "windows" of raster files.
-This feature allows you to operate on rasters that are larger than your
-computers RAM or process chunks of very large rasters in parallel.
+This feature allows you to work on rasters that are larger than your
+computers RAM or process chunks of large rasters in parallel.
 
 Windows
 -------

docs/working_with_datasets.rst

@@ -8,12 +8,12 @@ Working with Datasets
 Attributes
 ----------
 
-In addition to the file-like attributes shown above, a dataset has a number
-of other read-only attributes that help explain its role in spatial information
-systems. The ``driver`` attribute gives you the name of the GDAL format
-driver used. The ``height`` and ``width`` are the number of rows and columns of
-the raster dataset and ``shape`` is a ``height, width`` tuple as used by
-Numpy. The ``count`` attribute tells you the number of bands in the dataset.
+Besides the file-like attributes shown above, a dataset has some other
+read-only attributes that help explain its role in spatial information systems.
+The ``driver`` attribute gives you the name of the GDAL format driver used. The
+``height`` and ``width`` are the number of rows and columns of the raster
+dataset and ``shape`` is a ``height, width`` tuple as used by Numpy. The
+``count`` attribute tells you the number of bands in the dataset.
 
 .. code-block:: python
 

docs/writing.rst

@@ -18,7 +18,7 @@ Opening a file in writing mode is a little more complicated than opening
 a text file in Python. The dimensions of the raster dataset, the 
 data types, and the specific format must be specified.
 
-Here's a simple example of the basic rasterio functionality. 
+Here's an example of basic rasterio functionality. 
 An array is written to a new single band TIFF.
 
 .. code-block:: python