Prepared the what's new for v0.16.

docs/source/_static/layout.css

@@ -4,7 +4,20 @@
 
 pre {max-width: 70em;}
 
-div.section dl, div.section ul { max-width: 80em;}
+
+div.section dl, div.section ul {
+    max-width: 80em;
+}
+
+div.section {
+    /* Paragraph sections (e.g. in what's new) */
+    padding-bottom: 1em;
+}
+
+dl.class {
+    /* Sphinx documented classes. */
+    padding-bottom: 1.5em;
+}
 
 div.figure { padding-left: 5em; }
 

docs/source/_templates/layout.html

@@ -40,7 +40,7 @@
     <div class="footer">
     <p style="text-align: left; float: left; margin: 0px; padding: 0 0 0 5px;">Documentation licensed under the <a href="https://www.nationalarchives.gov.uk/doc/open-government-licence/version/2/" rel="license">Open Government Licence</a></p>
     {%- if show_copyright %}
-        &copy; <a href="{{ pathto('copyright') }}">British Crown Copyright</a> 2011 - 2017, Met Office
+        &copy; <a href="{{ pathto('copyright') }}">British Crown Copyright</a> 2011 - 2018, Met Office
     {%- endif %}
     {%- if last_updated %}
       {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %}

docs/source/matplotlib/feature_interface.rst

@@ -21,30 +21,44 @@ Natural Earth or GSHHS shapefiles.
 .. autoclass:: ShapelyFeature
 
 .. autoclass:: NaturalEarthFeature
+    :members: with_scale
 
 .. autoclass:: GSHHSFeature
 
+.. autoclass:: WFSFeature
+
 ----------
 
 To simplify some very common cases, some pre-defined Features exist as :mod:`cartopy.feature`
 constants. The pre-defined Features are all small-scale (1:110m)
 `Natural Earth <http://www.naturalearthdata.com>`_ datasets, and can be added with methods
 such as :func:`GeoAxes.add_feature <cartopy.mpl.geoaxes.GeoAxes.add_feature>`:
 
-=======================================  ==================================================
-Name                                     Description
-=======================================  ==================================================
-.. py:data:: cartopy.feature.BORDERS     Country boundaries.
-.. py:data:: cartopy.feature.COASTLINE   Coastline, including major islands.
-.. py:data:: cartopy.feature.LAKES       Natural and artificial lakes.
-.. py:data:: cartopy.feature.LAND        Land polygons, including major islands.
-.. py:data:: cartopy.feature.OCEAN       Ocean polygons.
-.. py:data:: cartopy.feature.RIVERS      Single-line drainages, including lake centerlines.
-=======================================  ==================================================
+=======================  ================================================================
+Name                     Description
+=======================  ================================================================
+.. py:data:: BORDERS     Country boundaries.
+
+.. py:data:: COASTLINE   Coastline, including major islands.
+
+.. py:data:: LAKES       Natural and artificial lakes.
+
+.. py:data:: LAND        Land polygons, including major islands.
+
+.. py:data:: OCEAN       Ocean polygons.
+
+.. py:data:: RIVERS      Single-line drainages, including lake centerlines.
+
+.. py:data:: STATES      Internal, first-order administrative boundaries (limited to the
+                         United States at this scale).
+                         Natural Earth have first-order admin boundaries for most
+                         countries at the 1:10,000,000 scale; these may be
+                         accessed with ``cartopy.feature.STATES.with_scale('10m')`` 
+=======================  ================================================================
 
 .. note::
 
-    Any Natural Earth dataset can easily be used by creating an
+    Any Natural Earth dataset can be used by creating an
     instance of :class:`cartopy.feature.NaturalEarthFeature`. For
     example::
 

docs/source/whats_new.rst

@@ -2,7 +2,7 @@ What's New in cartopy 0.16
 ==========================
 
 :Release: 0.16.0
-:Date: ??? 2018
+:Date: 21st Feb 2018
 
 Features
 --------
@@ -12,6 +12,85 @@ Features
   and has already made significant contributions to the Matplotlib interface,
   extended projections, and helped modernise the development infrastructure.
 
+* The :ref:`gnomonic-projection` was brought up-to-date to include the
+  ``central_longitude`` argument. (:pull:`855`)
+
+* Ryan May improved the formulation of the boundary ellipse for the
+  :class:`~cartopy.crs.Geostationary` projection and added the
+  ``sweep_angle_axis`` keyword argument. (:pull:`890`, :pull:`897`) 
+
+* Elliott Sales de Andrade made a number of micro-optimisations to the
+  Matplotlib interface, fixed a number of documentation issues with
+  Python 3 and added Matplotlib 2.0 & 2.1 compatibility. (:pull:`886`,
+  :pull:`901`, :pull:`780`, :pull:`773`, :pull:`977`)
+
+* Tick padding was added to the gridliner.
+  :data:`cartopy.mpl.gridliner.Gridliner.xpadding` and
+  :data:`~cartopy.mpl.gridliner.Gridliner.ypadding` relate. (:pull:`783`)
+
+* Ryan May added the :meth:`~cartopy.feature.NaturalEarthFeature.with_scale`
+  method to the NaturalEarthFeature class.
+  For example, it is now possible to access higher resolution land features
+  with ``cartopy.feature.LAND.with_scale('50m')``. In addition to this,
+  :data:`cartopy.feature.STATES` was added to easily access administrative
+  area boundaries that were previously only accessible by manually
+  constructing :class:`~cartopy.feature.NaturalEarthFeature` instances
+  (as is done in the :ref:`sphx_glr_gallery_feature_creation.py` example).
+  (:pull:`898`)
+
+* Daryl Herzmann and Robert Redl improved cartopy's internal conversion
+  between shapely objects and Matplotlib Paths. (:pull:`885` & :pull:`1021`)
+
+* Åsmund Steen Skjæveland fixed :meth:`cartopy.mpl.geoaxes.GeoAxes.tissot`
+  to use the documented units of kilometres, where before it had been using
+  metres. (:pull:`904`)
+
+* Andrew Dawson wrote a new tutorial for the user guide:
+  :ref:`understanding_transform`. (:pull:`914`)
+
+.. figure:: _images/understanding_transform-6.png
+   :target: tutorials/understanding_transform.html
+   :align: center
+
+* Daniel Kirkham and Daryl Herzmann made significant improvements to the
+  stability of polygon transformation. The changes reduce the frequency
+  of messages such as
+  ``Unidentified problem with geometry, linestring being re-added`` and
+  ``Self-intersection at or near point <X> <Y>`` occurring.
+  (:pull:`974` and :pull:`903`)
+
+* Chris Holdgraf and Corinne Bosley worked collaboratively to bring
+  `sphinx-gallery <https://github.com/sphinx-gallery/sphinx-gallery>`_ to the
+  cartopy docs. (:pull:`969`)
+
+* Ray Bell neatened up many of the examples to explicitly pass the coordinate
+  system when calling :meth:`~cartopy.mpl.geoaxes.GeoAxes.set_extent`.
+  (:pull:`975`)
+
+* Ryan May changed the default zorder of LAND and OCEAN to -1, thus fixing
+  an issue with LAND/OCEAN appearing above some data elements such as
+  vectors. (:pull:`916`)
+
+* Kevin Donkers added the 60 UTM projections example to the gallery
+  in :pull:`954`:
+
+.. figure:: gallery/images/sphx_glr_utm_all_zones_001.png
+   :target: gallery/utm_all_zones.html
+   :align: center
+
+* Andrey Kiselev added support for reading shapes with a third (Z) dimension.
+  (:pull:`958`)
+
+* Corinne Bosley standardised the docstring format for improved readability
+  and visual consistency. (:pull:`987`)
+
+* Cartopy now no longer enables :func:`shapely.speedups` at cartopy import
+  time. (:pull:`990`)
+
+* Mahé Perrette and Ryan May collaborated to improve the
+  :class:`~cartopy.crs.Stereographic` projection. (:pull:`929`)
+
+
 
 What's New in cartopy 0.15
 ==========================

lib/cartopy/examples/always_circular_stereo.py

@@ -1,8 +1,13 @@
 """
-Keep Boundary Circular
-----------------------
+Custom Boundary Shape
+---------------------
 
-Setting the boundary of an image to be circular.
+This example demonstrates how a custom shape geometry may be used
+instead of the projection's default boundary.
+
+In this instance, we define the boundary as a circle in axes coordinates.
+This means that no matter the extent of the map itself, the boundary will
+always be a circle.
 
 """
 __tags__ = ['Lines and polygons']

lib/cartopy/examples/favicon.py

@@ -1,6 +1,8 @@
 """
-Favicon
--------
+Cartopy Favicon
+---------------
+
+The actual code to generate cartopy's favicon.
 
 """
 import cartopy.crs as ccrs

lib/cartopy/examples/feature_creation.py

@@ -2,6 +2,16 @@
 Feature Creation
 ----------------
 
+This example manually instantiates a
+:class:`cartopy.feature.NaturalEarthFeature` to access administrative
+boundaries (states and provinces).
+
+Note that this example is intended to illustrate the ability to construct
+Natural Earth features that cartopy does not necessarily know about
+*a priori*.
+In this instance however, it would be possible to make use of the
+pre-defined :data:`cartopy.feature.STATES` constant.
+
 """
 __tags__ = ['Lines and polygons']
 

lib/cartopy/examples/features.py

@@ -2,6 +2,9 @@
 Features
 --------
 
+A demonstration of some of the built-in Natural Earth features found
+in cartopy.
+
 """
 __tags__ = ['Lines and polygons']
 

lib/cartopy/examples/global_map.py

@@ -2,6 +2,9 @@
 Global Map
 ----------
 
+An example of a simple map that compares Geodetic and Plate Carree lines
+between two locations.
+
 """
 __tags__ = ['Lines and polygons']
 

lib/cartopy/examples/hurricane_katrina.py

@@ -2,6 +2,9 @@
 Hurricane Katrina
 -----------------
 
+This example uses the power of Shapely to illustrate states that are likely to
+have been significantly impacted by Hurricane Katrina.
+
 """
 __tags__ = ['Lines and polygons']
 

lib/cartopy/examples/logo.py

@@ -1,6 +1,8 @@
 """
-Logo
-----
+Cartopy Logo
+------------
+
+The actual code to produce cartopy's logo.
 
 """
 import cartopy.crs as ccrs

lib/cartopy/examples/rotated_pole.py

@@ -2,7 +2,7 @@
 Rotated pole boxes
 ------------------
 
-This example demonstrates the way a box is warped when it is defined
+A demonstration of the way a box is warped when it is defined
 in a rotated pole coordinate system.
 
 Try changing the ``box_top`` to ``44``, ``46`` and ``75`` to see the effect

lib/cartopy/examples/un_flag.py

@@ -2,6 +2,9 @@
 UN Flag
 -------
 
+A demonstration of the power of Matplotlib combined with cartopy's Azimuthal
+Equidistant projection to reproduce the UN flag.
+
 """
 import cartopy.crs as ccrs
 import cartopy.feature as cfeature

lib/cartopy/examples/waves.py

@@ -1,6 +1,8 @@
 """
-Waves
------
+Filled contours
+---------------
+
+An example of contourf on manufactured data.
 
 """
 __tags__ = ['Scalar data']

lib/cartopy/mpl/geoaxes.py

@@ -1292,10 +1292,10 @@ def set_boundary(self, path, transform=None, use_as_clip_path=True):
 
         if self.background_patch is None:
             background = mpatches.PathPatch(path, edgecolor='none',
-                                            facecolor='white', zorder=-1,
+                                            facecolor='white', zorder=-2,
                                             clip_on=False, transform=transform)
         else:
-            background = mpatches.PathPatch(path, zorder=-1, clip_on=False)
+            background = mpatches.PathPatch(path, zorder=-2, clip_on=False)
             background.update_from(self.background_patch)
             self.background_patch.remove()
             background.set_transform(transform)