.travis.yml

@@ -51,7 +51,7 @@ install:
   - "if [ \"$GDALVERSION\" == \"master\" -o $(gdal-config --version) == \"$GDALVERSION\" ]; then echo \"Using gdal $GDALVERSION\"; else echo \"NOT using gdal $GDALVERSION as expected; aborting\"; exit 1; fi"
   - "python -m pip wheel -r requirements-dev.txt"
   - "python -m pip install -r requirements-dev.txt"
-  - "GDAL_CONFIG=$GDALINST/gdal-$GDALVERSION/bin/gdal-config python -m pip install --upgrade --force-reinstall -e .[test,plot]"
+  - "GDAL_CONFIG=$GDALINST/gdal-$GDALVERSION/bin/gdal-config python -m pip install --upgrade --force-reinstall --no-use-pep517 -e .[test,plot]"
   - "python -m pip install coveralls>=1.1"
   - "rio --version"
   - "rio --gdal-version"

AUTHORS.txt

 Authors
 -------
 
-* Sean Gillies
-* Matthew Perry
-* Kevin Wurster
-* Brendan Ward
-* Jonas Sølvsteen
-* Colin Talbert
-* James McBride
-* Erik Seglem
-* Vincent Sarago
-* Seth Fitzsimmons
-* James Hiebert
+* Alan D. Snow
+* Aldo Culquicondor
+* Alessandro Amici
+* Alexander
+* Alexander Ivanov
 * Amit Kapadia
-* Damon Burgett
-* Even Rouault
-* Kelsey Jordahl
-* Maxim Dubinin
-* Ryan Grout
-* Joshua Arnott
+* Andrew Annex
+* Andrew Catellier
+* Ariel Zerahia
 * AsgerPetersen
-* Mike Toews
-* Nick Grue
-* Alessandro Amici
 * Bas Couwenberg
-* Frédéric Bonifas
 * Ben Lewis
-* Johan Van
-* Chris Holdgraf
-* morrme
-* Chris Holden
-* cgohlke
-* Andrew Catellier
-* mwtoews
-* Martin Kaesberger
-* ngrue
-* Nat Wilson
-* Juan Luis Cano
-* Gregory Raevski
-* Tyler Erickson
-* Jeffrey Gerard
-* Jacques Tardie
-* Robin Wilson
-* Jonas
-* asmith26
-* Aldo Culquicondor
-* Alexander Ivanov
-* Ariel Zerahia
+* Brendan Ward
+* Caleb Robinson
 * Charlie Loyd
+* Chris Holden
+* Chris Holdgraf
+* Christoph Rieke
+* Colin Talbert
 * Damien Ayers
+* Dan "Ducky" Little
 * Dan Baston
-* Etienne B.
+* Darren Weber
+* Denis Rykov
+* Erik Seglem
+* Etienne B. Racine
+* Even Rouault
 * Filipe
+* Frédéric Bonifas
+* Gregory Raevski
+* Guillaume Lostis
 * Guy Doulberg
+* Ismail Sunni
+* Jacques Tardie
+* James Hiebert
+* James McBride
 * James Seppi
+* Jeffrey Gerard
+* Jennifer Reiber Kyle
 * Jeremy Hooke
 * Jesse Crocker
-* Joris Van
+* Johan Van de Wauw
+* Jonas Sølvsteen
+* Joris Van den Bossche
+* Joshua Arnott
+* Juan Luis Cano Rodríguez
+* Kelsey Jordahl
+* Kevin Wurster
 * Kirill Kouzoubov
+* Koshy Thomas
+* Leah Wasser
+* Lukasz
 * Martijn Visser
+* Martin Kaesberger
+* Martin Raspaud
 * Matt Savoie
+* Matthew Perry
+* Maxim Dubinin
+* Mike Taves
+* Nat Wilson
+* Nick Grue
+* Pablo Sanfilippo
 * Patrick Young
 * Pratik Yadav
+* RK Aranas
+* Raaj Tilak Sarma
+* Robert Sare
+* Robin Wilson
+* Ryan Grout
 * Sam Murphy
-* Talbert
-* Trevor R.H.
+* Sean Gillies
+* Seth Fitzsimmons
+* Trevor R.H. Clarke
+* Tyler Erickson
+* Vincent Sarago
 * Vincent Schut
-* Alan D.
+* Yuvi Panda
+* appanacca
+* asmith26
+* cgohlke
+* derekjanni
+* dnomadb
+* firas omrane
 * grovduck
-* Dan "Ducky" Little
+* jaredairbusaerial
+* morrme
+* sshuair

CHANGES.txt

 Changes
 =======
 
+1.1.0 (2019-10-07)
+------------------
+
+There have been no changes since 1.1b3.
+
+1.1b3 (2019-10-03)
+------------------
+
+Bug fixes:
+
+- A regression in WarpedVRT creation (#1799) has been fixed. This required
+  implementation of GDALDatasetH reference counting in DatasetBase.stop().
+
+1.1b2 (2019-10-02)
+------------------
+
+Bug fixes:
+
+- When built from the official source distribution rasterio 1.1b1 would not
+  import due to the omission of _transform.c from the list of extension sources
+  in setup.py. This has been fixed.
+
+1.1b1 (2019-10-01)
+------------------
+
+Deprecations:
+
+- Support for Python 2 is deprecated and a warning is raised from the
+  rasterio.compat module. This module will be deleted in a future version.
+
+New features:
+
+- Added a new ``tag_namespaces()`` method datasets that returns names of
+  metadata namespaces that can be passed to the existing ``tags()`` method
+  (#1740).
+- Zoom levels can be automatically computed by rio-overview (#511).
+- An alternative endpoint for S3-compatible network storage can now be set when
+  creating an instance of AWSSession (#1779). See GDAL's documentation of its
+  AWS_S3_ENDPOINT configuration option for more details.
+- The merge tool has a new ``method`` keyword argument that can be used to
+  override the default painter's algorithm. It takes an alternative method name
+  as a string or a callable. Please see the merge tool docstring for the
+  callable's signature (#1500).
+- A new ``rasterio.transform.from_gcps()`` function returns the Affine matrix
+  that is a best fit to given ground control points (#1749).
+
+Bug fixes:
+
+- Handle the AWS extension mentioned in #1159. Note that this does not enable
+  writing directly to S3.
+- A syntax error in the specification of a Python version marker for enum34 in
+  requirements.txt has been fixed.
+- Several cases of memory leaks involving temporary in-memory datasets have
+  been fixed. The rasterio test suite now runs without leaving any datasets
+  open.
+- The default mode for dataset sharing has been switch from ``sharing=True`` to
+  ``sharing=False`` to better serve development of multithreaded applications
+  (#1775).
+- Tests of rasterizing invalid shapes now catch the warnings about shape
+  skipping.
+
+Other:
+
+- The AUTHORS file has been updated and is now sorted by name (first name
+  first) or GitHub username.
+
 1.0.28 (2019-09-09)
 -------------------
 
@@ -204,7 +270,7 @@ Changes
 - The copy and copyfiles functions of rasterio.shutil now raise an exception
   when the source and destination paths identify the same dataset (#1569).
 
-1.0.11 (2019-11-30)
+1.0.11 (2018-11-30)
 -------------------
 
 - Prevent needless warning when making boundless reads with a fill value
@@ -218,7 +284,7 @@ Changes
   execute such code inside a `with Env()` block or set the GDAL_DATA and
   PROJ_LIB environment variables needed by GDAL.
 
-1.0.10 (2019-11-16)
+1.0.10 (2018-11-16)
 -------------------
 
 - Avoid segmentation fault when OSRGetAuthority* functions return null
@@ -229,7 +295,7 @@ Changes
 - Accomodate the Esri flavor of projection WKT (#1537).
 - Add missing raster offsets and scales properties (#1527).
 
-1.0.9 (2019-10-25)
+1.0.9 (2018-10-25)
 ------------------
 
 Bug fixes:

README.rst

@@ -14,7 +14,12 @@ Geographic information systems use GeoTIFF and other formats to organize and
 store gridded, or raster, datasets. Rasterio reads and writes these formats and
 provides a Python API based on N-D arrays.
 
-Rasterio supports Python 2.7 and 3.3-3.6 on Linux and Mac OS X.
+Rasterio 1.0.x works with Python versions 2.7.x and 3.5.0 through 3.7.x, and GDAL
+versions 1.11.x through 2.4.x. Official binary packages for Linux and Mac OS X are
+available on PyPI. Unofficial binary packages for Windows are available through other
+channels.
+
+Rasterio 1.0.x is not compatible with GDAL versions 3.0.0 or greater.
 
 Read the documentation for more details: https://rasterio.readthedocs.io/.
 
@@ -195,7 +200,7 @@ Linux
 Rasterio distributions are available from UbuntuGIS and Anaconda's conda-forge
 channel.
 
-`Manylinux1 <https://github.com/pypa/manylinux>`__ wheels are available on PyPI.```
+`Manylinux1 <https://github.com/pypa/manylinux>`__ wheels are available on PyPI.
 
 OS X
 ++++

debian/changelog

-rasterio (1.0.28-2) UNRELEASED; urgency=medium
+rasterio (1.1.0-1) unstable; urgency=medium
 
+  * Team upload.
+  * New upstream release.
   * Bump Standards-Version to 4.4.1, no changes.
+  * Drop clean-target.patch, applied upstream. Refresh remaining patch.
 
- -- Bas Couwenberg <sebastic@debian.org>  Mon, 30 Sep 2019 19:58:20 +0200
+ -- Bas Couwenberg <sebastic@debian.org>  Tue, 08 Oct 2019 06:03:39 +0200
 
 rasterio (1.0.28-1) unstable; urgency=medium
 

debian/patches/0001-Rename-rio-to-rasterio-Closes-788463.patch

@@ -9,7 +9,7 @@ There is already another package providing a binary "rio".
 
 --- a/setup.py
 +++ b/setup.py
-@@ -396,7 +396,7 @@ setup_args = dict(
+@@ -405,7 +405,7 @@ setup_args = dict(
      packages=['rasterio', 'rasterio.rio'],
      entry_points='''
          [console_scripts]

debian/patches/clean-target.patch

-Description: Fix clean target.
- GDAL/gdal-config may not be available outside the build chroot.
-Author: Bas Couwenberg <sebastic@debian.org>
-Forwarded: https://github.com/mapbox/rasterio/pull/1695
-
---- a/setup.py
-+++ b/setup.py
-@@ -81,6 +81,9 @@ extra_link_args = []
- gdal2plus = False
- gdal_output = [None] * 4
- gdalversion = None
-+gdal_major_version = 0
-+gdal_minor_version = 0
-+sdist_fill = []
- 
- try:
-     import numpy as np
-@@ -88,63 +91,64 @@ try:
- except ImportError:
-     sys.exit("ERROR: Numpy and its headers are required to run setup().")
- 
--try:
--    gdal_config = os.environ.get('GDAL_CONFIG', 'gdal-config')
--    for i, flag in enumerate(("--cflags", "--libs", "--datadir", "--version")):
--        gdal_output[i] = check_output([gdal_config, flag]).strip()
--
--    for item in gdal_output[0].split():
--        if item.startswith("-I"):
--            include_dirs.extend(item[2:].split(":"))
--    for item in gdal_output[1].split():
--        if item.startswith("-L"):
--            library_dirs.extend(item[2:].split(":"))
--        elif item.startswith("-l"):
--            libraries.append(item[2:])
-+if "clean" not in sys.argv:
-+    try:
-+        gdal_config = os.environ.get('GDAL_CONFIG', 'gdal-config')
-+        for i, flag in enumerate(("--cflags", "--libs", "--datadir", "--version")):
-+            gdal_output[i] = check_output([gdal_config, flag]).strip()
-+
-+        for item in gdal_output[0].split():
-+            if item.startswith("-I"):
-+                include_dirs.extend(item[2:].split(":"))
-+        for item in gdal_output[1].split():
-+            if item.startswith("-L"):
-+                library_dirs.extend(item[2:].split(":"))
-+            elif item.startswith("-l"):
-+                libraries.append(item[2:])
-+            else:
-+                # e.g. -framework GDAL
-+                extra_link_args.append(item)
-+        # datadir, gdal_output[2] handled below
-+
-+        gdalversion = gdal_output[3]
-+        if gdalversion:
-+            log.info("GDAL API version obtained from gdal-config: %s",
-+                     gdalversion)
-+
-+    except Exception as e:
-+        if os.name == "nt":
-+            log.info("Building on Windows requires extra options to setup.py "
-+                     "to locate needed GDAL files. More information is available "
-+                     "in the README.")
-         else:
--            # e.g. -framework GDAL
--            extra_link_args.append(item)
--    # datadir, gdal_output[2] handled below
--
--    gdalversion = gdal_output[3]
--    if gdalversion:
--        log.info("GDAL API version obtained from gdal-config: %s",
--                 gdalversion)
-+            log.warning("Failed to get options via gdal-config: %s", str(e))
- 
--except Exception as e:
--    if os.name == "nt":
--        log.info("Building on Windows requires extra options to setup.py "
--                 "to locate needed GDAL files. More information is available "
--                 "in the README.")
--    else:
--        log.warning("Failed to get options via gdal-config: %s", str(e))
- 
-+    # Get GDAL API version from environment variable.
-+    if 'GDAL_VERSION' in os.environ:
-+        gdalversion = os.environ['GDAL_VERSION']
-+        log.info("GDAL API version obtained from environment: %s", gdalversion)
-+
-+    # Get GDAL API version from the command line if specified there.
-+    if '--gdalversion' in sys.argv:
-+        index = sys.argv.index('--gdalversion')
-+        sys.argv.pop(index)
-+        gdalversion = sys.argv.pop(index)
-+        log.info("GDAL API version obtained from command line option: %s",
-+                 gdalversion)
- 
--# Get GDAL API version from environment variable.
--if 'GDAL_VERSION' in os.environ:
--    gdalversion = os.environ['GDAL_VERSION']
--    log.info("GDAL API version obtained from environment: %s", gdalversion)
--
--# Get GDAL API version from the command line if specified there.
--if '--gdalversion' in sys.argv:
--    index = sys.argv.index('--gdalversion')
--    sys.argv.pop(index)
--    gdalversion = sys.argv.pop(index)
--    log.info("GDAL API version obtained from command line option: %s",
--             gdalversion)
--
--if not gdalversion:
--    sys.exit("ERROR: A GDAL API version must be specified. Provide a path "
--             "to gdal-config using a GDAL_CONFIG environment variable "
--             "or use a GDAL_VERSION environment variable.")
--
--gdal_version_parts = gdalversion.split('.')
--gdal_major_version = int(gdal_version_parts[0])
--gdal_minor_version = int(gdal_version_parts[1])
--
--if gdal_major_version == 1 and gdal_minor_version < 11:
--    sys.exit("ERROR: GDAL >= 1.11 is required for rasterio. "
--             "Please upgrade GDAL.")
-+    if not gdalversion:
-+        sys.exit("ERROR: A GDAL API version must be specified. Provide a path "
-+                 "to gdal-config using a GDAL_CONFIG environment variable "
-+                 "or use a GDAL_VERSION environment variable.")
-+
-+    gdal_version_parts = gdalversion.split('.')
-+    gdal_major_version = int(gdal_version_parts[0])
-+    gdal_minor_version = int(gdal_version_parts[1])
-+
-+    if gdal_major_version == 1 and gdal_minor_version < 11:
-+        sys.exit("ERROR: GDAL >= 1.11 is required for rasterio. "
-+                 "Please upgrade GDAL.")
- 
- # Conditionally copy the GDAL data. To be used in conjunction with
- # the bdist_wheel command to make self-contained binary wheels.
-@@ -246,13 +250,14 @@ if os.environ.get('CYTHON_COVERAGE'):
- 
- log.debug('ext_options:\n%s', pprint.pformat(ext_options))
- 
--if gdal_major_version >= 2:
--    # GDAL>=2.0 does not require vendorized rasterfill.cpp
--    cython_fill = ['rasterio/_fill.pyx']
--    sdist_fill = ['rasterio/_fill.cpp']
--else:
--    cython_fill = ['rasterio/_fill.pyx', 'rasterio/rasterfill.cpp']
--    sdist_fill = ['rasterio/_fill.cpp', 'rasterio/rasterfill.cpp']
-+if "clean" not in sys.argv:
-+    if gdal_major_version >= 2:
-+        # GDAL>=2.0 does not require vendorized rasterfill.cpp
-+        cython_fill = ['rasterio/_fill.pyx']
-+        sdist_fill = ['rasterio/_fill.cpp']
-+    else:
-+        cython_fill = ['rasterio/_fill.pyx', 'rasterio/rasterfill.cpp']
-+        sdist_fill = ['rasterio/_fill.cpp', 'rasterio/rasterfill.cpp']
- 
- 
- # When building from a repo, Cython is required.

debian/patches/series

 0001-Rename-rio-to-rasterio-Closes-788463.patch
-clean-target.patch

docs/api/rasterio.path.rst

 rasterio.path module
-===================
+====================
 
 .. automodule:: rasterio.path
     :members:

docs/api/rasterio.rst

@@ -43,7 +43,6 @@ Submodules
    rasterio.shutil
    rasterio.tools
    rasterio.transform
-   rasterio.vfs
    rasterio.vrt
    rasterio.warp
    rasterio.windows

docs/api/rasterio.vfs.rst

-rasterio.vfs module
-===================
-
-.. automodule:: rasterio.vfs
-    :members:
-    :undoc-members:
-    :show-inheritance:

docs/cli.rst

@@ -9,8 +9,8 @@ cases are covered by CLI sub-commands and it is often more convenient
 to use a ready-made command as opposed to implementing similar functionality
 as a python script.
 
-The rio program is developed using the `Click <http://click.pocoo.org/>`__
-framwork.  Its plugin system allows external modules to share a common
+The rio program is developed using the `Click <http://click.palletsprojects.com/>`__
+framework.  Its plugin system allows external modules to share a common
 namespace and handling of context variables.
 
 .. code-block:: console
@@ -23,7 +23,9 @@ namespace and handling of context variables.
     Options:
       -v, --verbose           Increase verbosity.
       -q, --quiet             Decrease verbosity.
-      --aws-profile TEXT  Selects a profile from your shared AWS credentials file
+      --aws-profile TEXT      Select a profile from the AWS credentials file
+      --aws-no-sign-requests  Make requests anonymously
+      --aws-requester-pays    Requester pays data transfer costs
       --version               Show the version and exit.
       --gdal-version
       --help                  Show this message and exit.
@@ -243,7 +245,7 @@ Web Mercator (EPSG:3857),
 
     $ rio edit-info --crs EPSG:3857 example.tif
 
-set its `affine transformation matrix <https://github.com/mapbox/rasterio/blob/master/docs/georeferencing.rst#coordinate-transformation>`__,
+set its :ref:`affine transformation matrix <coordinate-transformation>`,
 
 .. code-block:: console
 
@@ -267,7 +269,7 @@ which can also be expressed as:
 
     $ rio edit-info --colorinterp RGBA example.tif
 
-See ``rasterio.enums.ColorInterp`` for a full list of supported color
+See :class:`rasterio.enums.ColorInterp` for a full list of supported color
 interpretations and the color docs for more information.
 
 
@@ -514,7 +516,7 @@ rm
 
 New in 1.0
 
-Invoking the shell's '$ rm <path>' on a dataset can be used to
+Invoking the shell's ``$ rm <path>`` on a dataset can be used to
 delete a dataset referenced by a file path, but it won't handle
 deleting side car files.  This command is aware of datasets and
 their sidecar files.
@@ -618,6 +620,8 @@ a raster dataset, do the following.
     [192457.13, 2546667.68, 399086.97, 2765319.94]
 
 
+.. _warp:
+
 warp
 ----
 
@@ -685,7 +689,7 @@ See `click-plugins <https://github.com/click-contrib/click-plugins>`__ for more
 information on how to build these plugins in general.
 
 To use these plugins with rio, add the commands to the
-``rasterio.rio_plugins'`` entry point in your ``setup.py`` file, as described
+``rasterio.rio_plugins`` entry point in your ``setup.py`` file, as described
 `here <https://github.com/click-contrib/click-plugins#developing-plugins>`__
 and in ``rasterio/rio/main.py``.
 

docs/faq.rst

+Frequently Asked Questions
+==========================
+
+Where is "ERROR 4: Unable to open EPSG support file gcs.csv" coming from and what does it mean?
+-----------------------------------------------------------------------------------------------
+
+The full message is "ERROR 4: Unable to open EPSG support file gcs.csv.  Try
+setting the GDAL_DATA environment variable to point to the directory containing
+EPSG csv files." The GDAL/OGR library prints this text to your process's stdout
+stream when it can not find the gcs.csv data file it needs to interpret spatial
+reference system information stored with a dataset. If you've never seen this
+before, you can summon this message by setting GDAL_DATA to a bogus value in
+your shell and running a command like ogrinfo:
+
+.. code-block:: console
+
+    $ GDAL_DATA="/path/to/nowhere" ogrinfo example.shp -so example
+    INFO: Open of 'example.shp'
+          using driver 'ESRI Shapefile' successful.
+
+    Layer name: example
+    Geometry: Polygon
+    Feature Count: 67
+    Extent: (-113.564247, 37.068981) - (-104.970871, 41.996277)
+    ERROR 4: Unable to open EPSG support file gcs.csv.  Try setting the GDAL_DATA environment variable to point to the directory containing EPSG csv files.
+
+If you're using GDAL software installed by a package management system like apt
+or yum, or Homebrew, or if you've built and installed it using ``configure;
+make; make install``, you don't need to set the GDAL_DATA environment variable.
+That software has the right directory path built in. If you see this error,
+it's likely a sign that GDAL_DATA is set to a bogus value. Unset GDAL_DATA if
+it exists and see if that eliminates the error condition and the message.
+
+If you're installing GDAL into a Conda environment or into a Python virtual
+environment (remember that the Rasterio wheels on the Python Package Index
+include a GDAL library and its data files) the situation is different. The
+proper data directory path is not built in and GDAL_DATA must be set.
+
+Rasterio 1.0.18, whether from PyPI or Conda, will set the GDAL_DATA environment
+variable to the correct location when it is imported, but only if it has not
+already been set. Previous versions of Rasterio tried to avoid patching the
+environment of the process, but there's really no better option.
+
+Get the latest version of Rasterio, 1.0.18, and use it without setting
+GDAL_DATA. You shouldn't experience the error condition or the message about
+it.

docs/index.rst

@@ -51,6 +51,7 @@ Rasterio supports Python versions 2.7 and 3.3 or higher.
    topics/index
    api/index
    contributing
+   faq
 
 Indices and Tables
 ==================

docs/quickstart.rst

@@ -6,7 +6,7 @@ This document explains how to use Rasterio to read existing files and to create
 new files. Some advanced topics are glossed over to be covered in more detail
 elsewhere in Rasterio's documentation. Only the GeoTIFF format is used here,
 but the examples do apply to other raster data formats. It is presumed that
-Rasterio has been `installed <./installation>`__.
+Rasterio has been :doc:`installed <installation>`.
 
 Opening a dataset in reading mode
 ---------------------------------
@@ -195,7 +195,7 @@ dataset's upper left corner, do the following.
     >>> row, col = dataset.index(x, y)
     >>> row, col
     (1666, 3333)
-    >>> band_one[row, col]
+    >>> band1[row, col]
     7566
 
 To get the spatial coordinates of a pixel, use the dataset's :meth:`~rasterio.io.DatasetReader.xy` method.

docs/topics/configuration.rst

@@ -55,10 +55,10 @@ Rasterio
 .. code-block:: python
 
     with rasterio.Env(GTIFF_FORCE_RGBA=True, CPL_DEBUG=True):
-        with rasterio.open('data/stefan_full_greyalpha.tif') as ds:
+        with rasterio.open('data/stefan_full_greyalpha.tif') as dataset:
            # Suite of code accessing dataset ``ds`` follows...
 
-The object returned when you call ``rasterio.Env()`` is a context manager.  It
+The object returned when you call :class:`rasterio.Env()` is a context manager.  It
 handles the GDAL configuration for a specific block of code and resets the
 configuration when the block exits for any reason, success or failure. The
 Rasterio ``with rasterio.Env()`` pattern organizes GDAL configuration into single
@@ -89,4 +89,4 @@ the default GDAL or format options.
 
 
 .. |WITHST| replace:: ``with``
-.. _WITHST: https://docs.python.org/2/reference/compound_stmts.html#withhttps://docs.python.org/2/reference/compound_stmts
+.. _WITHST: https://docs.python.org/3.7/reference/compound_stmts.html#the-with-statement

docs/topics/georeferencing.rst

@@ -37,6 +37,8 @@ argument.
    >>> with rasterio.open('/tmp/foo.tif', 'w', crs='EPSG:3857', **profile) as dst:
    ...     pass # write data to this Web Mercator projection dataset.
 
+.. _coordinate-transformation:
+
 Coordinate Transformation
 -------------------------
 

docs/topics/image_options.rst

@@ -6,7 +6,7 @@ These options come in two flavors:
 
     * **Configuration options** are used to alter the default behavior of GDAL
       and OGR and are generally treated as global environment variables by GDAL. These
-      are set through a ``rasterio.Env()`` context block in Python.
+      are set through a :class:`rasterio.Env()` context block in Python.
 
     * **Creation options** are passed into the driver at dataset creation time as
       keyword arguments to ``rasterio.open(mode='w')``.
@@ -18,7 +18,7 @@ GDAL options are typically set as environment variables. While
 environment variables will influence the behavior of ``rasterio``, we
 highly recommended avoiding them in favor of defining behavior programatically.
 
-The preferred way to set options for rasterio is via ``rasterio.Env()``.
+The preferred way to set options for rasterio is via :class:`rasterio.Env()`.
 Options set on entering the context are deleted on exit.
 
 .. code-block:: python
@@ -28,7 +28,7 @@ Options set on entering the context are deleted on exit.
     with rasterio.Env(GDAL_TIFF_INTERNAL_MASK=True):
         # GeoTIFFs written here will have internal masks, not the
         # .msk sidecars.
-        ...
+        # ...
 
     # Option is gone and the default (False) returns.
 
@@ -37,7 +37,6 @@ will convert them GDAL's internal forms.
 
 See the `configuration options`_ page for a complete list of available options.
 
-
 Creation options
 ----------------
 
@@ -52,19 +51,28 @@ Some of the common GeoTIFF creation options include:
   * ``PHOTOMETRIC`` to define the band's color interpretation
 
 To specify these creation options in python code, you pass them as keyword arguments
-to the ``rasterio.open()`` command in write mode::
+to the :func:`rasterio.open()` command in write mode.
+
+.. code-block:: python
 
     with rasterio.open("output.tif", 'w', **src.meta, compress="JPEG",
                        tiled=True, blockxsize=256, blockysize=256,
-                       photometric="YCBCR") as dest:
-        ...
+                       photometric="YCBCR") as dataset:
+        # Write data to the dataset.
+        
+.. note:: The GeoTIFF format requires that *blockxsize* and *blockysize* be multiples of 16.
+
+On the command line, ``rio`` commands will accept multiple ``--co`` options.
+
+.. code-block:: bash
 
-Or at the command line, ``rio`` commands will accept multiple ``--co`` options::
+    $ rio copy source.tif dest.tif --co tiled=true
 
-    rio copy source.tif dest.tif --co tiled=true
+These keyword arguments may be lowercase or uppercase, as you prefer.
 
-Note that some *configuration* options also have an effect on driver behavior at creation time.
+.. attention:: Some options may at a glance appear to be boolean, but are not. The GeoTIFF format's BIGTIFF option is one of these. The value must be YES, NO, IF_NEEDED, or IF_SAFER.
 
+.. note:: Some *configuration* options also have an effect on driver behavior at creation time.
 
 .. _configuration options: https://trac.osgeo.org/gdal/wiki/ConfigOptions
 .. _formats list: http://gdal.org/formats_list.html

docs/topics/masking-by-shapefile.rst

@@ -9,16 +9,15 @@ Using ``rasterio`` with ``fiona``, it is simple to open a shapefile, read geomet
         import rasterio.mask
 
         with fiona.open("tests/data/box.shp", "r") as shapefile:
-            features = [feature["geometry"] for feature in shapefile] 
+            shapes = [feature["geometry"] for feature in shapefile] 
 
 This shapefile contains a single polygon, a box near the center of the raster, so in this case, our list of features is one element long.
 
 .. code-block:: python
 
         with rasterio.open("tests/data/RGB.byte.tif") as src:
-            out_image, out_transform = rasterio.mask.mask(src, features,
-                                                                crop=True)
-            out_meta = src.meta.copy()
+            out_image, out_transform = rasterio.mask.mask(src, shapes, crop=True)
+            out_meta = src.meta
 
 Using ``plot`` and ``imshow`` from ``matplotlib``, we can see the region defined by the shapefile in red overlaid on the original raster.
 
@@ -32,6 +31,7 @@ Applying the features in the shapefile as a mask on the raster sets all pixels o
                          "height": out_image.shape[1],
                          "width": out_image.shape[2],
                          "transform": out_transform})
+
         with rasterio.open("RGB.byte.masked.tif", "w", **out_meta) as dest:
             dest.write(out_image) 
 

docs/topics/masks.rst

@@ -9,7 +9,7 @@ rows and columns as the dataset in which non-zero elements (typically 255) indic
 corresponding data elements are valid. Other elements are invalid, or *nodata*
 elements.
 
-The other kind of mask is Numpy's `masked array <http://docs.scipy.org/doc/numpy/reference/maskedarray.generic.html`_
+The other kind of mask is Numpy's `masked array <http://docs.scipy.org/doc/numpy/reference/maskedarray.generic.html>`__
 which has the inverse sense: `True` values in a masked array's mask indicate
 that the corresponding data elements are invalid. With care, you can safely
 navigate convert between the two mask types.