Surface is deprecated

The docs are hidden. The service warns when it is called.

Resolves #221

docs/api/mapbox.services.rst

@@ -84,14 +84,6 @@ mapbox.services.static\_style module
     :undoc-members:
     :show-inheritance:
 
-mapbox.services.surface module
-------------------------------
-
-.. automodule:: mapbox.services.surface
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
 mapbox.services.uploads module
 ------------------------------
 

docs/index.rst

@@ -47,10 +47,7 @@ Services
   - Render with GeoJSON overlays
   - Adjust pitch and bearing, decimal zoom levels
 
-- **Surface V4** `examples <./docs/surface.md#surface>`__, `website <https://www.mapbox.com/developers/api/surface/>`__
-
-  - Interpolates values along lines. Useful for elevation traces.
-
+- **Surface V4** **DEPRECATED**
 - **Uploads V1** `examples <./docs/uploads.md#uploads>`__, `website <https://www.mapbox.com/api-documentation/?language=Python#uploads>`__
 
   - Upload data to be processed and hosted by Mapbox.
@@ -100,7 +97,6 @@ Documentation
    datasets.md
    geocoding.md
    matrix.md
-   surface.md
    directions.md
    input_features.md
    static.md

mapbox/services/surface.py

@@ -1,11 +1,14 @@
+import warnings
+
 from uritemplate import URITemplate
 
 from mapbox.encoding import encode_waypoints, encode_polyline
+from mapbox.errors import MapboxDeprecationWarning
 from mapbox.services.base import Service
 
 
 class Surface(Service):
-    """Access to the Surface API V4"""
+    """Access to the Surface API V4 **DEPRECATED**"""
 
     api_name = 'surface'
     api_version = 'v4'
@@ -25,6 +28,10 @@ def surface(self,
                 interpolate=None,
                 zoom=None):
 
+        warnings.warn(
+            "The surface module will be removed in the next version. "
+            "It has no replacement.", MapboxDeprecationWarning)
+
         params = {
             'layer': layer,
             'fields': ','.join(fields),