Update NEWS and docs for the next release

NEWS

@@ -1,6 +1,17 @@
 Since version 1.11.0 Pycairo uses `Semantic Versioning
 <http://semver.org/>`__ i.e. the newest version is the latest stable one.
 
+.. _v1.17.0:
+
+1.17.0 - 2018-??-??
+-------------------
+
+* :class:`cairo.Surface` and :class:`cairo.Device` can now be used as context
+  managers. :bug:`103`
+* Fix a leak when a cairo error was raised.
+* Fix a leak when a mapped surface was GCed instead of unmapped.
+
+
 .. _v1.16.3:
 
 1.16.3 - 2018-02-27

README.rst

@@ -29,23 +29,22 @@ Features of the Pycairo bindings:
 
     import cairo
 
-    surface = cairo.SVGSurface("example.svg", 200, 200)
-    context = cairo.Context(surface)
-    x, y, x1, y1 = 0.1, 0.5, 0.4, 0.9
-    x2, y2, x3, y3 = 0.6, 0.1, 0.9, 0.5
-    context.scale(200, 200)
-    context.set_line_width(0.04)
-    context.move_to(x, y)
-    context.curve_to(x1, y1, x2, y2, x3, y3)
-    context.stroke()
-    context.set_source_rgba(1, 0.2, 0.2, 0.6)
-    context.set_line_width(0.02)
-    context.move_to(x, y)
-    context.line_to(x1, y1)
-    context.move_to(x2, y2)
-    context.line_to(x3, y3)
-    context.stroke()
-    surface.finish()
+    with cairo.SVGSurface("example.svg", 200, 200) as surface:
+        context = cairo.Context(surface)
+        x, y, x1, y1 = 0.1, 0.5, 0.4, 0.9
+        x2, y2, x3, y3 = 0.6, 0.1, 0.9, 0.5
+        context.scale(200, 200)
+        context.set_line_width(0.04)
+        context.move_to(x, y)
+        context.curve_to(x1, y1, x2, y2, x3, y3)
+        context.stroke()
+        context.set_source_rgba(1, 0.2, 0.2, 0.6)
+        context.set_line_width(0.02)
+        context.move_to(x, y)
+        context.line_to(x1, y1)
+        context.move_to(x2, y2)
+        context.line_to(x3, y3)
+        context.stroke()
 
 ----
 

docs/reference/devices.rst

@@ -17,6 +17,18 @@ class Device()
 
     .. versionadded:: 1.14
 
+    .. note::
+
+        .. versionadded:: 1.17.0
+
+            :class:`cairo.Device` can be used as a context manager:
+
+        .. code:: python
+
+            # device.finish() will be called on __exit__
+            with cairo.ScriptDevice(f) as device:
+                pass
+
     .. method:: finish()
 
         This function finishes the device and drops all references to external

docs/reference/surfaces.rst

@@ -48,6 +48,22 @@ class Surface()
    *Surface* is the abstract base class from which all the other surface
    classes derive. It cannot be instantiated directly.
 
+   .. note::
+
+      .. versionadded:: 1.17.0
+
+         :class:`cairo.Surface` can be used as a context manager:
+
+      .. code:: python
+
+         # surface.finish() will be called on __exit__
+         with cairo.SVGSurface("example.svg", 200, 200) as surface:
+             pass
+
+         # surface.unmap_image(image_surface) will be called on __exit__
+         with surface.map_to_image(None) as image_surface:
+             pass
+
    .. method:: copy_page()
 
       Emits the current page for backends that support multiple pages, but