From ff4bc7bf6730160931abb1edb12bcecf0be13076 Mon Sep 17 00:00:00 2001
From: Sean Gillies <sean.gillies@gmail.com>
Date: Tue, 8 May 2018 13:26:58 -0600
Subject: [PATCH] Surface is deprecated (#231)

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

Resolves #221
---
 docs/api/mapbox.services.rst | 8 --------
 docs/index.rst               | 6 +-----
 mapbox/services/surface.py   | 9 ++++++++-
 3 files changed, 9 insertions(+), 14 deletions(-)

diff --git a/docs/api/mapbox.services.rst b/docs/api/mapbox.services.rst
index 739af4f..f9cbeb2 100644
--- a/docs/api/mapbox.services.rst
+++ b/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
 ------------------------------
 
diff --git a/docs/index.rst b/docs/index.rst
index b6af6f0..ee772bd 100644
--- a/docs/index.rst
+++ b/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
diff --git a/mapbox/services/surface.py b/mapbox/services/surface.py
index 2dd3dcc..24d8837 100644
--- a/mapbox/services/surface.py
+++ b/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),